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INTRODUCTION 


WHITE LIGHTNING 
by Oasis Software 


White Lightning is a high level graphics developrent systan for the Spectrum 48k. 
It is aimed primarily at the user \oki.o has ccrrrrercial games writing in mind and has 
the patience to learn a sizeable new languag-e. It is not a garres designer and 
stunning results probably 'w00 1 t re produce::I. overnight, b.lt it does have the power 
and flexibility to prcrluce software of a ccrrrrercial standard (with a little 
perseverance!). 
software produce::1 using White Lightning can be marketed without 
restriction, although, we w::mld be very grateful if you felt you could pop a sna.11 
credit oo the sleeve. 
If you're l<X>king for a publisher - don't forget us ! I 


Assembly language has three a:lvant.ages over roost high level languages: 
speed, 
flexibility and cx:rnpactness. 
During the running of an arcade garre, the processor 
spends nost of its t..ine rranipulating screen data, and if the appropriate ccmnands 
are .implenented in the language, the execution 11overhead 11 is very sna.11. 
Add to 
this the fact that considerable tiJre has been spent en the routines themselves to 
cptimise execution speed, and we feel m:,st machine cede programrers "-Uuld t:e hard 
pressed to better White Lightning for speed. 
As far as flexibility is ooncerned, 
White Lightning has al.roost 300 cannands as -Ell as access to 81\SIC and rrachine 
language if required. 
A lot of the tricky routines like rotations and 
enlargements are already irrplemented for you. 
As far as carpactness g:Jes, Forth 
itself prcrluces ve.ry cxirpact crrle, rut there is, of oourse., the overhead of the 
language itself. Assanbly language has four najor drawbacks. 
Firstly, you've got 
t.o learn it. Having rrastered rrachine axle, program devel~nt is very sl<J\11 
carpared with a typical high level language, there is oo "crash protection" 
whatsoever, and t.o prcrluce effective results, you nee::l a fairly intimate knCMledge 
of the rrachine you' re working with. 


BASIC has several points in its favour, these are: excellent crash protection, 
extremaly readable source axle and a relatively short learning curve. 
These 
features nake BASIC a very good intrcrluction to prograrrming for the hobbyist, rut 
for the serious garres writer, the language is insufficient in terms of 00th its 
speed and flexibility. 


Because White Lightning is Forth b:tsed it has virtually the speed of rrachine code, 
no knowledge of the rrachine is required, the source code is relatively readable, 
and it is fairly \!oell protected fran crashing. 


If you 00 have any queries ooncerning White Lightning, then ;,.e can t:e oontacted ~ 
phone oo (0934) 419921. 
If possible, please restrict calls to the periods 9 am to 


11 am or 6 pn to 6. 30 pn. If this is oot ronvenient ""' are here all day. If your 
query is a detailed one then it's probably better to write in. 
We are also 
interested to hear of any extensions or routines you nay develop, and if 
sufficient interest is &K7tiffl WE! will start a News Letter, and possibly, even a 
User Group. 


SPRITE DEVELOPMENT 


Ioclu:ied with White Lightning is a sprite generator. This cares cx:rrplete with a 
predefined character set which, when suitably o:mbined, makes up 167 full 
characters. The predefined characters cover Asteroids, Pac-Man, Scramble, 
Defender, Space Invaders, City Bcmber, Lunar Lander, Frogger, Centipede, Dcnkey 
Kcng and rrany nore. Yoo can use them as they are, custanise them, or design up to 
255 of your own sprites. The developement software allows you to reflect, spin or 
invert. When you have finishe::1 work, or be~ sessions the whole lot can te 
sinply saved to tape. 


IDEAL 


The nain part of th8' package is the White Lightning language itself. The language 
can be thought of as being divida3. into 'bio parts: firstly, there is a super fast 
integer Forth, which conforms to a standard Fig-Forth, hlt secorrlly, and of nost 
iltportance to garres designers, there is the IDFAL sub-language. IDFAL stands for 
"Interrupt Driven Extendable Animation Language ". 
IDFAL has a dictionary of over 
100 words, which can be freely mixed with Forth, or, as we shall see, can be 
accessed fran BASIC. 


Interrupt Driven 


Forth/IDEAL words can be executed under interrupt: this rreans that programs can be 
run in foreground and background at the sane tine. Sq,pose, for instance, the 
program you are writing involves a scrolling 00.ckdrop, which has been defined in a 
sprite 6 screens wide. A program can l::e run in background to handle the scrolling 
backdrop, and a separate program written in fore:;Jrourrl to oontrol all of the 
characters which rrove within the backdrop. This will free the user £ran cx:rrplex 
timing calculations to get a arooth scroll and is one of the rrost p:::,werful 
features of the entire package. 
Backgram:l words can be executed q;:, to 50 tbres a 
second. 


Extendible 


Forth is extendible and was chosen as the rrost suitable h::>st language for IDFAL 
because of this ex:trenely useful feature. New words can be defined in temt.s of any 
of the Forth/IDE'AL words, or your CMrl previously defined 1,,0rds. This neans you can 
create diagonal scrolls for instance, by a:mbining individual scrolls. 


Animation Language 


Very careful planning ""'1eflt in to the designing of the IDFAL ani.m3.tion language, to 
rrake it as p:lrtable as p:,ssible tetween micros. If you I w written a very 
successful program for ooe micro, you can rrove the same code across without too 
rrn.r:h difficilty. The cnly major changes necessary, are changes to accaoodate the 
different screen foma.ts, ie the m1nber of ool l.lTl'ls and rows. 
You OOn' t nee:! to 


"'°rry al::x:>ut the a:rrplexities of various neoory mappings, IDEAL a::>es that for you. 
Serre jnplemantations will not allow attributes to l:e roved separately fran pixel 
data, so to be certain of higher portability, rrove attributes and data together. 


ACCESS FROM BASIC 


If you are not familiar with Forth and want to get reasonable software quickly, 
you can a•cess the IDF.AL language fran PASIC. Programs will no longer be i;x:>rtable 
and you "'°n't get quite the same spee:l and polish, b.tt perfectly goo:1 programs 
can, and have, been written this way. More rremory will be used for BASIC source, 
so bear all this in mind before deciding to put off learning Forth! 
Most of the 
useful PA.SIC cxmnands that handle sound and graphics, such as OOAW, CIRCLE, BEEP 
and so on, have been inplernented in Spectra Forth. Whenever possible, call then 
fran Forth and not PASIC. The interpretation and initial floating point 
manipulation of BASIC o:mnands are avoided, and cxmnands will therefore execute 
rrore rapidly fran Forth. 


·OPERATING INSTRUCTIONS 


1) 
Rewind the tape rrarkerl "Whl te T.,ightning". 
Disconnect interface 


l i f fitted. 


2) 
Load using IDAD"" then stop the tape. 
White Lightinig will aut.o-run. 


3 l 
Once loade:i, you will get the praiq,t IDAD SPRITES Y/N. 


4) 
If it's the first time you've use:i the package, type Y to load the 
dem::mstration sprites, which follow directly after White Lightning on the 
sane tape. 
There is a section of data before the sprites which doesn't 


load, b.lt don' t w:irry about this, this is infonnation used by the sprite 
developnent package. 
Once loade:i, the IDAD OOURCE Y/N praipt will appear. 
Press N t.o enter White Lightning or, if you wish to Load scue source cx:de 
place the apprcpriate cassette in the recorder, press PLAY and then type Y. 


5 l 
To RUN the deoonstrations, just I.OAD using IOAD"" and the program will 
auto-nm. 


6 l 
To RUN the Sprite DelJel.opnent Software just type WAD"" and again the 
pro:;Jram will auto-run. 


TO THE NEWCOMER 


When you have run the d.E!oonstration tape and have seen what can t:e chne, this may 
give you the incentive to l earn all you can to produce full specification garres 
for yourself. 
The author of this rranual knew nothing of White Lightning before 
starting this project, bJt can pranise you that after coly a few tx>urs of 
experimentat ion, becarre fairly 00.ept and. had the confidence to want to go further. 
It nay all look a little a:mplicated at first, b..It please te assured, that after a 
short time, and only a little effort, the fog really does clear! 


Mike Butler. 


INTRODUCTION 


SECTION 1 


THE SPRITE GENERATOR PROGRAM 


by Paul Newnham 


The Sprite Generator Program v.es developed to o:::npliment the White Lightning 
language. 
The language is CXJRprised of ccmnands for rranipulating sprites and 


screen data b.tt dc>es oot have the facility to directly design graphics characters. 
This rreans there are ~ 
phases to games creation. 
The first involves designing 


and e:Hting your graphics characters with the sprite generator program, and the 
second involves the writing of the gane itself using the White Lightning language. 
In practice the two areas of \toOrk will probably te carried out simultaneously. 
For those of you \i,llo are not artistically inclined, there are boo sets of 
previously defined graphics d:laracters ready to use. 


The Arcade Character Set 


The arcade character set is an integral part of the sprite generator program - 167 
characters are provided in all. 
To see these, IDAD and run [EM) B using IDAD "". 


The [EM) will auto-run. 
This will tell you which characters can be called up by 
which number, using Function Key z. 
These characters are surrrrarised as tile 


penultimate pa.rt of this section. 


The Demonstration Sprites 


Directly after White Lightning oo side A. you will find the demonstration eprites. 
By running the tape past White Lightning and using the IDAD SPRITE:$ FRO! '12\PE 
faciltity, these can be Loaded and edited for your own use. 
The various sprites 


are tabulated at the end of this section. 


USING SPRITES WITH WHITE LIGHTNING 


Once you have o:JTt)leted an editing session, the sprites generated should be Saved 
to tape for further editing sessions, or for use with the White Lightning language 
itself. 
To Load ;,our sprites into White Lightning: 


1. 
Load White Lightning using I!W) '"' 


2. 
Insert the tape oontaining your sprites into the tape recorder and press Y in 
response to the "IOAD SPRITES Y/N" prcrrpt. 
The sprites will be Loaded at the 
address at \ttbich they ~e saved using the sprite generator prcgram. 


COLD START 


If you enter the sprite generator progr am via a row start, then all sprites 
previously stored will be cleared and all system variables reset. 
If, for 
instance, you wish to use the deoonstration sprites, you \«'Juld enter via a CDLD 
start. 
The program must always be initially entered via a CXJLD start. 


WARM START 


If you enter the program via a WARM start then all sprites will be oonserved and 
all system variables left unchanged. 
It is provided principa.lly for re-entering 
the program after an accidental ERF.AK or mROR. 
If you do accidentally l!IBAK; 


type: = 3 and then enter via the WARM start . 


BUFFER SIZE 


When White Lightning runs programs in Background. m::rle (see section 3) the top end 
of rrerory is used as a scratch pad. 
The size of this area depends on the 
operation of the program and calculating the am:mnt you need to reserve is covered 
in section 3. 
When the sprite generator program is entere:l the bJffer has a 
default size of 256 bytes. 
This is probably Im.1Ch larger than require:l, b..it until 
you are familiar with the package or need to save a few extra bytes, just leave 
the ruff er at 256 bytes. 


THECHR$SOR 


CHR.$ ~ is the abbreviation used throughout this text for character s:;iuare, and 
refers to the 8 by 8 grid to the left of the sprite screen. 
This is the area used 
to create and e:lit sprites one character at a ti.rre. 


THE SPRITE SCREEN 


This is the area of screen 15 characters by 15 characters oo which sprites are 
created, developed, transfonred and generally \tOrked on. 


THE CHR$ SOR CURSOR 


This is the non-destructive flashing cursor which is used to design and edit the 
character currentiy held in the CHRS si;J<. 


THE SPRITE SCREEN CURSORS 


These are the b.o flashing cursors, displayed in the Ro,, teneath the sprite screen 
and the 0011.1111 to the right of the sprite screen. 
'!hey are used to indicate the 
position of the top left hand oorner of the screen windOW" currently t:eing operate:i 
upon. 
The actual cursor positions are rreasured fran the top left hand oorner of 
the sprite screen and are displayed in real tine oo the screen as X ros ( oolum) 
and Y ros <row>. 
Tep left is x ros l Y ros l. Botton right is x ros F Y ros F. 


SCREEN WINDOWS 


The area of the screen currently being t«>rked on is referred to as the screen 
window. 
Its p;,sition is defined by X ros and Y ros, which oorrespond to the 
positions of the sprite screen cursors, ard its dimensions are defined by SPRITE 
HEIGHT and SPRI'IB r»cm. 
To see the screen windOW" you are currently \I.Orking oo 


just press F. 
The window will flash. 


SPRITE LIBRARY 


This refers to the set of sprites you are currently \I.Orking with and can oontain 
up to 255 sprites or use 12500 bytes. If your sprite library needs nore than 
12500 bytes you can use the nerging procedure detailed in section 3 to Load and 
rrerge 1l'Ore than ooe sprite library into White Lightning. 


OPERATING INSTRUCTIONS 


Insert the Sprite Generator Program Tape, type IDAD"" and load into the o::rrputer 
as oormal. 


Once loaded, the program will auto-nm and the screen message, "CDLD CR WARM 
srART" will appear. 
If this is the first execution of the program or if you wish 
to clear the sprite rrerory, press C for a COLD START. 


A further screen rressage will ro,, appear asking if you wish to change the bJ.ffer 
size - this has a default value of 256 bytes. 
For ro,,, press N. 
This function 
will becare ll'Ore apparent later. 


NOTES: 


1. 
A WARM S'I'ART will oot destroy any sprites already in rrerory and if ever the 
program is accidently cause:1 to BIBAK, type OOIO 3 and in reS{X)nse to the screen 
prarpt, execute a WARM START. 


2. 
A OOLD START will destroy any and all sprites defined in rremory. 


3. 
WARM STARTs can ooly be executed after an initial OOLD START. 


GETTING FAMILIAR WITH THE FUNCTION KEYS 


Now lets get familiar with sane of the Ftmction Keys - a full list will be found 
at the end of this section. 


THECHR$SQR 


This is the grid square oo which you create and edit characters for your o-,m 
sprite library. 
To rrove the cur so~: 


1. Press the 5 key for each rrovarent to the left. 


2. 
Press the 6 key for each 1TOVarent downward. 


3. 
Press the 7 key for each rrovement ~d. 


4. 
Press the 8 key for each rrovarent to the right. 


N0o1 that you Jene,,,, hcM to rrove the cursor, let I s fill in a few 9:}Ua.res: 


1. 
Move the cursor to any square that you like and release the keys. 


2. 
Press the 9 key to set the square. 


3. 
New ITOve the direction keys and fill in a few ITOre squares. 


No,,, that we have set 9:J'l\e squares, what alx>ut deleting a few of them? This is 
simple: 


1. 
Move the cursor to a square that you have set and release the keys. 


2. 
Press the O key to clear the square. 


Ne,,.., have a go at setting and clearing s:::rre squares, just to get used to it. 


The Sprite Screen Cursors 


New that you' re used to rroving the CHR$ SCR cursor around, rroving the sprite 
screen airsors is a piece of cake: 


1. 
Move the X airsor ~ pressing SYMOOL SHIFT and the 5 or 8 key to ITCve left or 
right respectively. 


NJTE: 
If you've never l::een able to renan1::er which is the X or which is 
the Y rrovanent, 
remember this little saying: 


X is a cross - if you say it quickly it sounds like, X is across - 
which it is! 


2. 
Move the Y airsor l:7y" pressing SYMB)L SHIFI' and the 7 or 6 key to rrove up or 
down respectively. 


Character Building 


No, not yours - Wilding up characters to make up sprites! 
You've probably got 
quite a rress in the OIR$ 50:l, so let's clear it: 


1. 
Press the Q key and reSfX)nd to the pranpt in the text line ~ pressing Y and 
the QIR$ 9;)l will clear. 


Just to get you used to a similar function, let's clear the Sprite Screen as well, 
even though it's clear: 


1. 
As you can see, to clear the OIR.$ ~ 
press Q, to clear the sprite screen 
press SYMIDL SHIFT Q - cunning eh? 


New that we have clear screens we can start to go places. 
Have a go at this: 


1. 
Move the X and Y cursors to 1 and 1 respectively. 


2. 
Press the z key C to call up a draracter fran the Arcade Library) and enter the 


~ numl:e.r 75 follCMed ~ ENI'ER. 
A space invader type character will appear oo the 
sprite screen. 


3. 
Press the K key and answier Y to the prc:npt and hey presto - the character has 
been placed in the OIR$ Sl;)l. 


This will illustrate quite nicely hcYw a character is b.Jilt up. 


Have a go at changing this character using the 5, 6, 7 or 8 keys to rrove the OIR$ 
~ 
cursor and the 9 and O keys to set or clear a square. 
You w::>n't l:e able to 
see the OiR$ 51,)l cursor at the rranent - just press one of the cursor keys and it 
will flash for you. 


Let's GET your 'new character' into rrerory: 


1. Move the sprite screen cursors to X ros 4 and Y POS 4 (SYMIDL SHIFT 5, 6, 7, 
and 81 


2. 
Press the J key and answer Y to the question. 


3. 
Yoor new- character was place:l en the sprite screen fran the OIR$ ~ 
by using 
the J key. 
Your original dlaracter is still there at X POS 1 Y POS 1. 


4. 
Now press the S key to give your character a sprite m.unber. 
For oow, just 
enter the number 1 and press ENI'ER. 


5. 
Press the G key to GET the character into rreoory as a sprite and answer Y to 
the prarpt - your dlaracter will flash to confirm. 


N<:M, let I s prove that your character is in rreoory: 


1. 
Press the 5™.IDL SHIFT Q to clear the sprite screen. 


2. 
Press S to tell the cx:rrputer Wich sprite you are calling up (there is cnly 
ooe at the narent of rourse) • Enter 1 followed tr,, ENI'ER. 


3. 
Now press P to PUT the sprite to the sprite scr6?ell and answer Y to the 
question. 


4. 
New you will be given four rrore cptions. 
Den' t worry about 2, 3 and 4 for oow 


- lE just W:illt to place cur sprite oo the sprite screen. 
Press 1, and there it 


is! 


You will notice that although you correctly got your own sprite PUT back to the 
sprite screen, the original diaracter £ran the Arcade Library wasn't. 
This 
exanple leS to show you that any actions that you call for, will only happen to 
the dlaracter that the sprite screen cursors are p::,inting to, as lE p::,inted out in 
the Intro1uction. 


You will also notice that the am.$ SOl still contains your new character - have a 
look to a:npare. 


We have seen h:>w to call up a character £ran the Arcade Library and h:,w, in 
essence, to b.lild up a character in the CHR$ S<)l. 
There is another way to Wild 
up a character: 


1. 
Press SYMOOL SHIFT Q to clear the sprite screen. 


2. 
Press the D key, answer Y to the question, and enter the following, very 
carefully, pressing ENTER after each entry: 


al 
H24 126 H9D 255 HFF 153 129 102 


3. 
Guess who's 00.ck! (You should have a space invader type character). 


This is the DIROCT ~TA INPUT. 
Direct Data characters are b.lilt up fran 8 bytes 
of data, one t¥te at a ti.rre. 


N)TE: 
~ta can ooly be entered using values in the range O to 255 Decimal or 
HOO to HFF HEX, 
'!he character H must prece:le a HEX entry. 


Let's do a quick review of the functions that W;:! have used: 


1. 
OIR$ ~ 
- cursors, 5, 6, 7 and 8 keys to rrove and the 9 and O keys to set and 
clear squares. 
The Q key clears the CHR.$ ~- 


2. 
SPRITE S::REEN - 5 and 8 to rrove the X cursor CX is across rarember) and 6 and 
7 to rrove the Y cursor. 
The SYMOOL SHIFT and Q keys clear the sprite screen. 


3. 
The Z key calls q:, the ARCADE CHARJ>CTIB LIE!RARY - 
l to 167. 


4. 
The K key transfers a character fran the SPRITE OCREEN to the OIR$ sc;Jl. 


5. 
The J key transfers a character fran the OIR$ SCR to the SPRITE OCREEN. 


6. 
The s key defines and sutsequently calls up a p:trticular SPRITE. 


7. 
The G key GETs your sprite into rnerrory. 


8. 
The P key PUTs your sprite £ran rrerory onto the SPRITE OCREEN. 


9. 
The D key enables you to enter a character by DIRECT J:Yl.TA to the SPRITE 
OCREEN. 


You've userl quite a few functions! 
Have a go at calling up scme rrore Arcade 
Characters, change them if you wish, then GET them into rrerory and P{Jl' them onto 
the SPRITE s:::REEN. 


The Information Rectangle 


MEMORY LEFT 12486 
)( POS 4 
Y POS 4 
SPRITE 65266 
SPRITE HEIGHT • 1 
SPST 
66266 
SPRITE LENGTH . 1 
SPND 
65280 
SPRITE NUMBER. 1 
The text line 


This is a rcost useful facility which can be of great service to you. 
Most of the 


infonnation is fairly obvious, bJt W;'ll run through it all: 


1. 
MEMJRY I.EFT, as it says, is the anount of rrenory available for sprites; these 


are the sprites that you define and do not inclu::le the Arcade Characters - to use 
these, of course, you must define them as sprites by GETting them into rrenory. 


2. 
X FOS Y ros, these are the current positions of your SPRITE 9:R.EEN X and Y 


cursors wi. th reference to the figures oo top and to the left of the SPRITE 
OCREEN. 
. 


3. 
SPRITE, this indicates the (X)sition, in rrerory, \fflere your definerl sprite is. 


4. 
SPST, indicates the SPrite space Sl'art p:>int, in rrerrory. 
(Before any sprites 
are definerl this has an initial value of 65280). 


5. 
SPNO, indicates the SPrite space eND p:>int, in rnerrory. 


6. 
SPRITE HEIGHT, indicates the height of your define:l sprite, in character 


squares, as indicated by the figures at the top and to the left of the SPRITE 
OCREEN. 
(This has an initial value of 1). 


7. 
SPRITE UN:n'H, indicates the length of your define:l sprite, in character 
squares, as indicated by the figures at the top and to the left of the SPRITE 
s:REEN. 
(This has an initial value of ll. 


8. 
SPRITE Nl1-11El, indicates the sprite currently definerl. 
(This has an initial 
value of 1). 


9. 
The Text Line, to show the Function callerl ~, and the available cptions. 


More Function Keys 


Let I s rrove on. 
IREAK the prog-ram - CAPS SHIFl'/ERFAK keys, type ooro 3 and press 
ENI'ER. 
Execute a (l}LD (C) START and answer N to llJFFER SIZE CHANGE. 
Nothing of 
what you have previously OOne is in rrerory. 
(We could have cleared all your 
sprites by defining them (S key) and pressing W (WIPE SPRITE), b.Jt depending oo 
how rrany you defined. whilst experimenting, it oould have been a lengthy process!) 


New have a go at this: 


1. Clear the sprite screen (SYMIDL SHIFT Q) 


2. 
Press X to activate the INK variable and then set it to 2. 


3. 
Press C to activate the PAPER variable and then set it to 7. 


4. 
Press B to activate the EIUGHT switch and then press 1 to switch it CN. 


5. 
Press V to activate the FIASH variable and then press O to switch it OFF. 


6. 
Press A to activate the ATllUilJl'E switch and then press l to switch it CN. 


You will have noticed, that toth PAPER and FIASH were already set to 7 and 0 
respectively fran the OOLD start: we ooly run through than all for ccmpleteness 
and to get used to using them. 


What you have OOne, is to set the attrib.Jtes for the character we are ab:>ut to 
define, so lets do that: 


1. Press z to call up the arcade characters, answer Y to the prarpt, and enter 
150 follc,..,,ed by ENl'ER - there you have it - a ra:i Dalek. 


New in order to define this dlaracter as a sprite, we need to GET it into nemory. 


1. Press S to set ~ a sprite and type 10, followed C1f ENI'ER. 


New ,-,.e' 11 need to set up the screen windcM: 


1. Press L to activate the sprite length variable and then press 2 foll<M:!d by 
ENI'ER. 
You will see the windCM flash red across the top half of the character. 


2. 
Press H to ac:tivate the SPRITE HEIGIIT variable and then press 2 followed. by 
ENI'ER. 
Na.v you will see the new window flash. 


New convert this character into a sprite by GETting it into rremory: 


1. Press G to activate the GET function and anS'w'er Y to the prarpt. 
Again the 
screen wind.CM will flash, confirming that the character has been oor into rrenory. 


Move the sprite screen X cursor +2 (SYMBJL SHIFI' 8 twice). 
Activate the PUT 
function (P), respond with a Y to the pranpt and press 1 to Pl7I' your new sprite to 
the screen. 


NCM ....e' re going to mirror this second character and GET it into rremory as another 
sprite b.lt with different attributes: 
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1. 
Press E (Screen Functions), answe.r Y and press 2 (Mirror) - the character is 
reflected! 


2. 
Now press S (Sprite Nl.lllberl and enter 11. 


3. 
Press G (GET) and then Y - again it flashes to confirm. 


We now have two sprites, one facing left and one faci ng right. Let's set sare new 
attributes. 


1. 
Press X (INK) and enter 4 (green). 


2. 
Press I to activate the Attribute Dlrrp facility. 


3. 
Move the sprite screen X cursor 1 place to the right and press I again - the 
top half is done! 


4. 
Move the sprite screen Y cursor 1 place down and press I. 


5. 
Finally, rrove the sprite screen cursor one place to the left and press I again 
- there you have it, a red character to the left and a green one to the right. 


If you want to &Wap the oolours the other way around - yes you' re right this can 
be oone: 


1. Position the sprite screen c..ursors to X FOS 1 Y POS 1. 


2. 
We will have to set q;> the screen wind.OW" for the exchange: 


Press L (Length Variable) and enter 4 - the window will flash. 


3. 
Press E ( Screen Functions) , answer Y to the prarpt and press 3 to MIRROR 
ATIRIBOI'ES - watch the screen as you press 3, it happens very quickly! 
The re1 
Dalek beoares green and the green Dalek becares red. 


Right then - we'll nove co a little. 
We 1ll consider sare sprite operations. 
These are cperations which take place in rretory oo the stored sprites. 
We' 11 


begin by setting llJ a rBii sprite CX1l'l)rising two arcade characters and then go co 
to dlange their i;ositions in the sprite in neoory. Have a go at this: 


1. 
Clear the sprite screen (SYMB)L SHIFI' Q). 
ton't worry about your previous 


characters - you'll probably rananber that they are still in narory as sprites 10 
and 11. 


2. 
Make sure that the sprite screen cursors are set to X ros 1 Y ros 1. 


3. 
Set 1NK (Xl to 6 (yellow). 


4. 
Set PAPER (Cl to 0. 


5. 
Set FLASH (V) to 0. 


6. 
Set !RIGHT (B) to 1. 


7. 
Set l\TlR (A) to 1. 


8. 
Press z (Arcade Character) and enter 149 (a Robot). 
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9. 
Move the sprite screen X cursor by +2. 


10. Change the INK Cx,l to 4 (green). 


ll. Press z (Arcade Character) and enter 151 C another Rol:x:>t) • 


OK, you should have b«:> robots oo the sprite screen - lets define then as a 
canbined sprite: 


1. 
Move the cursors to X POS 1 Y POS 1. 


2. 
Press L (Length Variable ) and set to 4. 


3. Press H (Height Variable) and set to 2. 


4. 
Press s (Sprite Nunberl and enter 12. 


5. 
Press G (GET Function) and respond to the prarpt with Y. 


We have IXlW set up a 4 by 2 sprite oontaining 00th dlaracters. NcM" lets dlange 
then over in rrenory: 


1. Press M (Sprite Maoory Functions), respond to the prarpt with Y, and press 2 
(MIRROR) - nothing happens oo the sprite screen - this is a rrenory function. 


Let's prove that the sprite has been altered: 


1. 
MoV'e the sprite screen Y cursor by +3. 


2. 
Press P (Pl11') respond to the prarpt with Y and press 1 - the sprite has been 
reflected - 


We can return the attributes to their fonrer Rclx>ts quite easily: 


1. Press M (Sprite Mem:>ry Funct i ons >, respond to the praJt)t with Y, and press 3 
(Mirror Attributes l. 


2. 
McNe the Y cur sor by +3 and press P (PIJI'), respond to the prarpt with Y and 
press l - 
J'lOW' the attributes have mirrored. 


Let I s rrove on a little further OCM. 
We now look at a second sprite transformation 
- rotation. 
Try the follc""'1"ing: 


1. Clear the sprite screen and set the X and Y cursors to X POS l Y POS 1. 


2. 
Set INK (X) to 1 (blue). 


3. 
Set PAPER (Cl to 7 (..t,ite). 


4. 
Set FLASH CV) to 0. 


5. 
Set !RIGHT CB) to 1. 


6. 
Set ATlR (Al to 1. 


7. 
Press z (Arcade Character) and enter 151 Ca Robot) . 


B. 
Set HEIGffr (HI to 2 and IElim'H (LI to 2. 


9. 
Set the Sprite Number (S) to 13, then press G to GET the character as a 
sprite. 


10. Mcwe the X cursor by +2. 


11. Press R (RorATE), and enter the new sprite m.m"Cler, 14. 


12. Press P (Pill) and press 1 - a RoOOt rotated by 90 deg-rees! 


New that we have sprite 14 as a 90 degree rotation of sprite 13, why not go a 
little further ? Try this: 


1. 
Move the X cursor by +2. 


2. 
Press R (ROI'ATE) and enter the new sprite number, 15. 


3. 
Press P (Pill) and press 1 - this new robot has reen rotated by 180 de:Jrees 


fran it's original orientation. 


To prcrluce the final (270 degree> orientation: 


1. 
Move the X cursor by +2. 


2. 
Press R (RorATE) and enter the new sprite number, 16. 


3. 
Press P (Pill') and press 1 - this has prcrluced the final orientation. 


New let' s look at attribute handling in nure detail - clear the sprite screen and 
position the X and Y cursors to X POS 1 Y POS 1. 
The following OtoU exant;>les will 
show 00W to CDWnload and pick-q:, attributes l::etween the attribute variables and 
the sprite screen: 


1. 
Press X ( INK I and set to 3 (nag en ta I • 


2. 
Press C (PAPER I and set to 2 C red I • 


3. 
Press V (FLASH) and set to l 
CONI. 


4 . 
Press B (lRIGffrl and set to O (OFF). 


5. 
Press A (ATIRI and set to 0. 


6. 
Press I CATllUBUI'E C(H>) - 
the attributes will appear oo the sprite screen. 


7. 
New set all the attributes, X, C, V, B, and A to 0. 


e. 
Press u (PICK lP ATI'RIBl1I'ES) and the attributes on the screen will re loadal 
into the attribute variables. 
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This next exanple illustrates cne of the ITOre cxnplicat.ed functions of the 
generator - GETting a sprite into a larger sprite: 


1. 
Clear the sprite screen and position the cursors to X POS 1 Y POS 1. 


2. 
Press L (Length) and enter 4, then press H (Height) and enter 4. 


3. Press E (Screen Functions) and press 1 (INVERI'). 


4. 
Press S (Sprite Nrnlberl and enter 17, then press G CGEll'). 


5. 
Molle the X cursor ~ +4. 


6. 
Press x (INK) and set to 0. 


7. 
Press C (PAPER) and set to 6 (yellow). 


8. 
Press V (FLASH) and set to O (OFF). 


9. 
Press B CERIG!ffl and set to 1 COO). 


10. Press A CATIR l and set to 1. 


11. Press z (Arcade Character) and then enter 149. 


12. Press L (Length) and enter 2, then press H (Height) and enter 2. 


13. Press S (Sprite Nrniberl and enter 18. 


14. Press G CGEll'l. 


15. Press SPACE key (Place snall sprite into large sprite) - enter snall sprite as 
18, larger sprite as 17, Rew as 1, Colurm as 1 and BLS (1), as you get each 
prrnpt. 


16. M01Te the X cursor by +2. 


17. Press P (Pl1l'), answer the prarpt with Y and then press 1 - there you have it, 
your Rdx>t inside the square. 


Let's 11Dve en to look at sooe of the utility functions - Test and Wipe. 


L 
Clear the sprite screen and position the cursors to X POS 1 Y POS 1. 


2. 
Press z (Arcade Character) and enter 135. 


3. 
Press L (Length) and enter 2, then press H (Height) and enter 2. 


4. 
Press S (Sprite Number) and enter 19. 


5. 
Press G (GET). 


6. 
Press L (Length) and enter 10, then press H <Height l and enter 10. 


7. 
Clear the sprite screen. 


8. 
Press T (Test Sprite) and note that the information rectangle oontains the 


following: 
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A) 
SPRITE HEIGHT = 2 
B) 
SPRITE I..E'JGI'H = 2 
C) 
SPRITE lOll3ER = 19 
D) 
MEM:>RY IBFT 
= The remaining rreroory for sprites. 
El 
SPRITE 
= Start address of sprite being tested.. 


A function is providerl to Wipe a sprite fran rrenory and adjust I,X>inters. 
I.eave 
everything as it is and try: 


1. 
Press W (Wipe Sprite) - rerrenber sprite 19 has alrE;OO.y been defined. 
ResEX)nd 
to the prarpt with Y. 


2. 
Press T (Test Sprite) and an error message will appear oo the text line - 
SPRITE ID =ER EXISTS. 


While wa are oonsidering error nessages, have a go at this: 


1. 
Press z (Arcade Character) and then press 63. 


2. 
Press S (Sprite NWlber) and press 12 - an error nessage will ~, SPRITE 
ALRFADY IEFINED. 
Sprite number 12 is not oorrupted in any way, nor is the ooe you 
have p.1t to the screen. 
All that you need to 00 is choose a different sprite 


number 1'hich has oot already been allocated. 


There's one area wa' ve been avoiding all the way through - the Lo:Jic Functions. 
We don't want to wade into the depths of B::>olean algebra here, but instead, 
provide a few exarrples which tx,pefully show the application of the XOR, CR and AND 
operations to this part of the package. 
They are provided. for a:lvance::l 
applications ooly and their results are surrmarised on the sprite generator panel. 
Let' s see what they 00: 


1. Clear the sprite screen and (X)Sition the cursors to X ros 1 Y POS 1. 


2. 
Press X -UNK) and set to 3 (ll'agenta). 


3. 
Press C (PAPEll) and set to O (black). 


4. 
Press V (FLASH) and set to 0. 


5. 
Press B (BRIGHT) and set to 1. 


6. 
Press A (ATIR) and set to 1. 


7. 
Press Z (Arcade Character) and enter 149 (Robot). 


8. 
Press L (Length) and enter 2, then press H (Height) and enter 2. 


9. 
Press S (Sprite Nl>llber) and enter 21, then G (GITT) to Get the sprite. 


10. Move the X cursor by +2. 


11. Press P (Pill) and respond to the prcnpt with 1. 


12. Press z (Arcade Character) and enter 151 (Robot). 


13. Press O (Lcgical Sprite Functions) and press 1. 
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14. Move the x cursor l7f +2. 


15. Press P (PUT) arp respond with l - the characters have been "CRed" <rrerged ). 


Let's take this a little further and CR with the screen: 


1. Clear the sprite screen and p:,sition the cursors to X FOS l Y ros l. 


2. 
Press x CINK) and set to 1 Cbluel. 


3. 
Press C (PAPER) and set to 7 (white) . 


4. 
Press V (FLASH) and set to 0. 


5. 
Press B C !RIGHT) and set to 1. 


6. 
Press A CAT!Rl and set to 1. 


7. 
Press z (Arcade Character) and enter 141 (Explosion) - you probably think 
we're going to blCM up the Rc:bot! 


8. 
Press L (Length) and enter 2, then press H (Height) and enter 2. 


9. 
Press S (Sprite Number) and enter 22, then G (GE:r) sprite 22. 


10. Move the X cursor l7f +2. 


11. Press z (Arcade Character) and enter 149 (Robot). 


12. Press P (PlJl') and enter 2 - sprite number 22 has been "CRed" with whatever was 
on the screen. 


13. Move the X cursor by +2. 


14. Press P (Pur) and enter 1 - the explosion was unaffecte::l! 


Nc"'1 let' s take a look at a second logical q,eration - the AND function: 


1. Clear the sprite screen and posi t ion the cursors to X FOS 1 Y ros 1. 


2. 
Press P (PUT) and enter 4, sprite 22 has been "ANDed." with the screen - as the 
screen was enpty, nothing happened. 


3. 
Press P (Pl.11') and enter 1 - the sprite is still there! 


New, lastly, let's look at the Y.DR function: 


1. Clear the sprite screen and rrove the cursors to X ros 1 Y POS 1. 


2. 
Press z (Arcade Character) and enter 151 CROOOt). 


3. 
Press P CPUI') and enter 3 - the ROOOt has blown up! CA.t last I here you say 
!). 


16 


Now one of the interesting properties of the logical XOR, is that if the cperation 
is repeated, the original character is restored - to rrend the Robot: 


1. Press P (Pl1I') and enter 3 - a fully restored ROOOt! 


Well, there you have it. 
In fact, the only functions renaining that have oot been 
covered by an exanple are : 


1. Relocate Sprites ( < (SYMB:JL SHIFr R) ) . 


2. 
save sprites to Tape ( N:Yl' (SYMIDL SHIFr S) l. 


3. 
Load Sprites £ran Tape C - 
CSYMOOL 9-II Fr J ) ). 


The "Relocate Sprites" does sirrply that, it relocates sprites in rre:nory. 
Just 
enter a relocation length - positive to rrove srites to higher rrerory and negative 
to rrove sprites to lower rrerory. 
This function is oot often usa:1 in fact and 


should 1:e used with great care! 


The "Save Sprites" function is ve.ry straight forward - just follow the screen 
instructions. 
After the sprites have teen saved you will 1:e asked to rewind the 


tape to ve.rify the saved data. 


The "Load Sprites" function is similar to the above - just follow the screen 
instructions. 


It should 1:e ooted that whenever sprites are saved or loaded, there are 3 distinct 
sets of data ....tiich the generator stores and retrieves. 


CONCLUSIONS 


Well, there' s oothing to stop you ra,;, ! 
Going through the exanples will help you 


to familiarise yourself with all of the Function Keys. It w::,n' t re long refore 
you'll be happy to press oo by yourself - 
happy sprite generating.! 


The thing to 00 ro..t, is to press oo with Spectra Forth and IDFAL, these really are 
not as frightening as they nay first appear - after seeing the daro program, what 
rrore incentive do you need ! 
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SECTION2 


SPECTRA FORTH 
by Stuart Smith 


Forth is an extraordinary cxrrputer language developed originally for the oontrol 
of Radio Telescopes, by an Anerican named Charles ~re. 


Forth is neither an interpreter oor a canpiler, b.Jt canbines the best features of 
lx>th to produce a super-fast, high level language, incorporating the facilities 
offered by an interactive interpreter and the speed of exeaition close to that of 
machine-axle. 
In order to achieve these fantastic spee:is, Forth erq;:>loys the use 
of a data, or cx:mputation stack, en which to OOld the data or the operations to be 
perforned, ooupled with the use of Reverse Polish Notation (RPN). 
This may be 
quite a rrouthful, bJ.t RPN is very easy to use and understand with only a little 
practic-e - in fact, Hewlett Packard use RPN oo rrany of their calculators. 


All standard Forths use integer arithretic for their operations and can handle 1.4> 
to 32 bit precision if required - floating p:>int mathenatics routines could be 
inoorporated, bJt with a reduction in the execution speeds of a prcqram. 


White Lightning consists of a standard Fig-Forth rrodel, bu.t with over 100 
extensions to the standard \OCabulary of Forth words. 
There are t"'10 irrportant 
extensions to White Lightning: the first is the ability to ac-cess al.nost ALL of 
the Spectrum's c,;,m BASIC cxmnands, just as you \IOUld when writing a RJ\SIC program, 
and with the addition of many of the high resolution graphics cxrrmands (CIRCLE, 
CRAW, etc.). 
Coupled with the incredible execution speeds of White Lightning, the 
possibilities are limitless! 
The second, and possibly nost :important addition, is 
the IDFAL sub-langu,ge. 


In addition to the basic \OC.abulary of White Lightning \!Ords, the user can very 
easily AOO his own NEW KlROO using previously defined \toOrds, thus extending the 
vocabulary and Wilding q;, as a:rrplex a \!Ord as is necessary to 00 the t.ask in 
hand. 


Fully structure:l prograrrming nethcrls are also 8ft)loye:l as a fundanental feature of 
Forth through the use of the structure:l control sequences inclu:led, such as: 


IF ••••• ELSE ••••• ENDIF 
00 • • ••• lNrIL 


The standard Spectrum e:litor can be used to create lines of White Lightning source 
code for later cxmpilation. 
n:, not allow lines to excee:i 64 characters - any 


characters after this are ignored. 
The standard Forth line e:litor is inclu:led for 
CO'ft)atibili ty with existing text. The source oode is store:1 in rrerory fran $0:00 
onwards, and can be IDADerl or SA.VEd to tape as and when required. 
Once the source 
code is cxmplete, it may then be canpiled into the White Lightning dictionary for 
later execution. 


Inclu:led in this <XlCUlrentation is a glossary of Fig-Forth terms ( courtesy of the 
RJRTH INTEREST GROUP,PO rox 1105, SAN CARLOS, CA 94070). 


Spectra Forth ""8.s written by Stuart Snith, the author of the extrenely successful 
mAGONFDRIB, and is an enhanCEmant of a program written by the Forth Interest 
Group - to whan we offer our thanks. 


At the t..i.rre of writing, floppy discs are not read.Hy available for the Spectrum 
and instructions referring tD discs should be interpretei as accessing RAM. 
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AN INTRODUCTION TO SPECTRA FORTH 


This intrCXluction does not set out to teach Forth progranrning, bJt rather to serve 
as a supplenent to available texts on the subject; references incllrle: 


'Starting Forth' by Brcxlie, publishe:i by Prentice Hall. 
'IntrOO.uction to Forth' by Knecht, publishai by Prentice Hall 
'Discover Forth' by Hegan, p..iblished by MO::iraw Hill. 


White Lightning syntax oonsists of Forth w:>rds or literals, separated by spaces 
and terminated by a carriage return. 
A valid name must not oontain any anbedded 


spaces since this will t:e interpreted as two distinct words, and must te' less than 
31 characters in length. 
If a w:>rd is entered which does not exist or has been 
spelt wrongly, or the numrer entered is not valid in the current tase, then an 
error rressage will te displayed. 
To canpile and execute programs created using 
the &litor type IDAD <CR>. 
Throughout these exarrples <OD rreans 'PRESS .ENI'ER'. 


e.g. 
-FINE 
will generate an error message O since the \roUrd does 
not exist. 


HEX l 7F'l 
will generate an error massage O since z is not valid 


in hexadecimal base. 


Other error rressages inclu:le: 


srACK EMPTY 
srACK FOIL 
DICTIONARY FOIL 


In order to prog-ram in White Lightning, it is necessary to define new ~rds based 
on the ~rds already in the vocab.llary. 
Values to be passed to these ~rds are 
pushed onto the stack and if required, the 1Ai0rd will pull these values £ran the 
stack, cpe.rate en them, and push the result onto the stack for use by another 
Lightning \lloOrd. 
As rrentioned previously, Spectra Forth (as with all Forths) uses 
Reverse Polish Notation and inte:Jer numl:ers, therefore oo precedence of q:ierators 
is available, thus all q:,erations are performed in the sequence in which they are 
found oo. the stack. 


e.g. 
1 2 + 3 • is equivalent to 3*(1+2) 


As can be seen, in RPN, the q;:,erators are input after the mnnbers on which they 
have to q:ierate have been input. 


We will nc,w discuss sare of the 1Ai0rds in greater depth. 


1. INPUT /OUTPUT Operators. 


EMIT 
: 
This will take the number held on the top of the stack and display it 
on the terminal, as its original AS:II character. 


e.g. 
HEX 
41 
EMIT 
IB 
<CR> 


will instruct the Forth to rrove into hexadecimal node, push 41H onto the stack, 
and then take that number and display it on the terminal - in this exarrple the 
character displayed will be an "A". 
The actual character displayed rray l::e any of 
the recognisable ASCII characers, a graphic character, or a oontrol cx:rle depending 
on the value of the numl:er oo the stack. 
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EMITC 
As EMIT b.lt Crntrol characters are also dealt with. 


KEY 
This will poll the keyboard, ..,it for a key to be pressed and push 
the ASCII <X>de for that key onto the stack, without displaying it on 
the terminal. 


e.g. KEY' 
Press "A" oo the keyl::oard 


will instruct the carputer to wait for a key to l:e presserl (pres s the "A") and 
then push the A5CII value of this key, in this case 41H (\lvhere the 'H' inplies 
Hexadecimal 41 ie 65 decimal l onto the tq, of the stack. 
In order to display this 
character, try the following exanple: 


Type: 


KEY EMIT <Cl!> 


but be sure to hit the <Cl!> very quickly. 


Noif hit any key and its AOCII value will be printed foll"'""'1 17,' Cl<. 
So if you 
type "A" it w:,uld print "]'.()K". 
If you were tcx, slow you've rKJW got two cursors! 
Ignore the top ooe and try a:Jain. 
This problem only cx:curs J:ecause when you press 
<CR> to enter the exarcple, it irmEdiately executes and you've possibly still got 
<CR> held down. 
In a oonnal Forth definition you ~' t have this problem. 


CR 
This will transmit a carriage return and line feed to the display. 


COOvert the nmiter held on the stack using the current BASE and 
print it oo the screen with a trailing space. 


e.g 
SUpp::>se the stack oontains 16H and BASE is decimal (10), then • will print 
22 ( this is 16 +. 6); if BASE were hexadecimal ( 16), then • 'AOuld print 16. 


In order to see this working ,.,;e will alter the BASE and push numbers ooto the 
stack - r€!1l8nl:e.r, that just by typing in a valid number will result in it being 
pushed ooto the stack. 
There are - 
,.,ras to alter the EASE: 


HEX 
Use hexadecimal base 


DECIMAL : 
Use decimal base 


Try: 


(i) 
HEX 1F7 . <CR> (Where <CR> rreans press ENTER). 
This will print 1F7 
. 


( ii l 
00::IMAL 2048 • <Cl!> 
This will print 2048 


(iii ) 00::IMAL 2048 HEX • <Cl!> 


This will print 800, since this is the HEX equivalent of 2048. 
Renember that . will rerrove the number fran the stack that it is printing. 


U. 
: 
Prints the nunber held on the top of the stack as an W"'ISigne:::l number. 


e.g. 
HEX C000 U. <Cl!> 


will push C000 ooto the stack and then print it. 
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If ,.,.,ie use just . ,.,.,ie will get a negative result. 


HEX C000 • <CR> 


will print -4000 


: 
Print the value oontained at the crldress en top of the stack using the 
current base. 


St.t)[X)se the top of the stack oontains FF40H, location FF40/ 41H contains 0014H, and 
current BASE is 10 (DEX:IMAL), then ? will print 20 \obich is the decimal equivalent 
of 14 Hex. 


TYPE 
This uses the top '1W) numbers held on the stack and will print a 
selected number of characters starting at a specific 
address ooto the screen. 
The top numl:er oo the stack is the 
character oount and the second number is the address to 
start at. 


e.g. 
HEX 6100 20 T'tPE <CR> 


(Note that 6100H is i;,,shed ooto the stack and 20H is i;,,shed oo top of it 20H = 
'!OP; 6100H = second). 
This will print 20H (32) ASCII characters oorresponding to 
the data starting at a:ldress 6100H • (Note that much of the cutput will 00 
unreccgnisable unless the data oontains oorrect ASCII crrles, such as for numbers 
and letters) . 


DUMP 
This takes the top number oo the stack arrl prints cut 80H bytes 
starting at this al.dress. 


This is used in the form . " character string " and will display 
the string aontained within " " on the screen. 


e.g. 
• " 'llilS IS A OfARAC'rrn. SIRIN;; 
11 <CR> 
will i;,,t '.IRIS IS A CllARJ\CTffi srRJNi oo the screen. 
Note the spaces between the 


string and the quotes. 


SPACE 


SPACES 


This will display a single blank/space oo the screen. 


This will display n spaces on the screen, \obere n is the numter oo the 
top of the stack. 


e.g. 
IE::IMAL 10 SPJ\CES <CR> 


will print 10 spaces oo the screen. 


2. MATHEMATICAL DPERATORS 


+ 
: 
This will add the top ~ 
minl::ers on the stack and leave the result 
as a single number. 


e.g. 
l 2 + • <CR> 


will pri nt the value of l + 2 = 3 oo the screen. 
Note that the two top nUllbers 


are rem:>ved fran the stack, being replaced by a single number - this is true of 
nost Forth o::mnands, in that they reroove the values which they require to use fran 
the stack and i;,,sh the result ooto the stack. 
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For the p.llp)ses of the following exant)les, let us refer to the m:mbers oo the 
stack as follows: 


Nl 
top 
number oo stack (i.e. first to be raroverl) 


N2 = second number oo stack (i.e. second to be raooved) 
N3 = third number oo stack < i. e. third to t:e 
ranoved) 


To demonstrate this, let us p.ish three numbers onto the stack by typing: 


HEX 0lFA 0019 1F47 <CR> 


The stack will look like this: 


1F47 
Tep of stack 


0019 
0lFA 


Note that this illustrates the prq:erty of the stack, that it is, Last In First 
Out or UFO; therefore \E have: 


Nl 
1F47 
N2 = 0019 
N3 
= 
0lFA 


So if \E type: 


CR • CR • CR • CR <CR> 


We get 1F47 
19 
lFA 


We will now resurre our explanation of the rrathematical cperators. 


: 
This will subtract the top number oo the stack fran the second nmtl::er 
on the stack and leave the result as the top m.:mt>er. 


i. e. 
Nl = N2 - Nl 


e.g. 
Decimal 7 11 - 
• <rn> 
will print -4, since the stack t«>uld oontain 


Nl 
N2 
11 
7 
'IDS (Tep of stack) 


before the subtraction, and 


Nl 
-4 
'IDS 


after the subtraction. 


: 
This will multiply the top b«> numbers oo the stack and leave the 
result on the top of the stack. 


i.e. 
Nl=NlxN2 


e.g. 
CEX:IMAL 140 20 * . <rn> 


=uld print 2800 


22 


/ 
: 
This will divide the second number on the stack l:r:{ the first number, 
and leave the result oo the top of the stack. 
i.e. 
Nl=N2/Nl 


e.g. 
00::IMAL 1000 500 / • <CR> 


will print 2 


MAX 
: 
This will leave the greater of th~ top bo.u nwnbers on the stack. 


e.g. 
371 309 MAX • <CR> 


will print 371 


MIN 
: 
This will leave the ST1aller of the bo.u numbers on the stack. 


e.g. 
371 309 MIN • <CR> 


will print 309 


ABS 
: 
This will leave the aL.:;.0lute value of the top number on the stack as 
an unsigned number. 


i.e. 
Nl = ABS(Nl) 


e.g. 
47 AES • <CR> 
will print 47 


-47 AES • <CR> 
will print 47 


MINUS 
: 
This will negate the top number on the stack. 
i.e. 
Nl = -Nl 


e.g. 
418 MINUS • <CR> 


will print -418 


-418 MINUS • <CR> 


will print 418 


1 + 
: 
add 1 to the top m.unber on the stack 


Nl=Nl+l 


2 + 
: 
add 2 to the top number on the stack 
Nl=Nl+2 


1- 
subtract 1 fran the top number on the stack 


Nl=Nl-1 


2- 
: 
subtract 2 fran the top number on the stack 


Nl=Nl-2 


e.g. 
196 2- • <CR> 


will print 194 
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MOD 
: 
This will leave the remainder of N2/Nl on the top of the stack with 
the sane sign as N2 


e.g. 
17 3 M)D • <CR> 


will print 2 
(17/3 = 5 remainder 2) 


/MOD 
This will leave the renainder and the quotient oo the stack of N2/Nl 
such that the qtX>tient becares the top number oo the stack and the 
remainder beccmes the secx:,nd. 


e.g. 
17 3 /MJD • CR • <CR> 
will print 5 (quotient) 
2 (remainder) 


3. STACK OPERATORS 


DUP 
: 
This will duplicate the top number oo the stack. 


e.g. 
719 DUP •• <CR> 


will print 719 719 


DROP 
: 
This will drop the number fran the top of the stack. 


e.g. 
111 222 mop . <CR> 


will print 111 


SWAP 
: 
This will swap the top - 
numbers oo the stack. 


e.g. 
111 222 ~ 
•• <CR> 


will print 111 222 


OVER 
: 
This will cx,py the second number oo the stack, making it a new number 
at the top of the stack without destroying the other mmters. 


e.g. 
111 222 OVER • CR • CR • <CR> 


will print 111 


222 
111 


since the stack l:efore OJER was: 


222 
'.IDS 
111 


and after OVER is: 


111 
'.IDS 
copy 
222 
111 


ROT 
This will rotate the top three numbers on the stack, bringing the 
third nurnl:er to the top of the stack. 
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e.g. 
1 2 3 RClr • CR • CR • <CR> 


will print 1 


3 
2 


since the stack before ror was: 
3 
'.IDS 
2 
1 


and after ror is: 
1 
'.IDS 
3 
2 


4. OTHER OPERATIONS 


: 
This will store the second numrer on the stack at the address held on 
the top of the stack. (pronounced. "store"). 


e.g. 
Slt)p:)se the stack is as follows: 


HEX C000 
'.IDS 
FFEE 


This will store FFEE at address COOO/COOl 
i. e. 
EE at C000 
FF at C00l 


If ""' key in HEX FF00 C000 ! <CR> 
this will store FF00 at C000/C00l 
i. e 
C000 contains low byte 00 
C00l contains high byte FF 


REl!e!lber that each 16 bit number takes 1t> 2 bytes. 


0 
: 
This will replace the address held on the top of the stack, with the 
16 bit oontents of that address. (Pronounced. "at") 


S~ the neoory contents are as follows: 


Address: 
6100 6101 6102 6103 6104 6105 
Caltents: 00 
C3 
8F 
70 
00 
C3 


then 6100 @ • <CR> 
will print C300 


If you wish to deal with single bytes, then a variation of the above will te 
used . 


Cl 
: 
Will store a single byte held in the second number oo the stack at the 
oodress held oo the top of the stack. 


e.g. 
FF COO0 C! <CR> 


will store a single byte FF ft a:ldress C000. 
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C@ 
This will fetch the single l¥te held at the address at the top of the 
stack - this single byte will te pushed on the stack as a 16 
bit number, rut with the high byte set to zero. 


With reference to the rrerory oontents shown previously, 
if we key in COOO C@ • <rn> 


this will print FF (and oot FF00 as with @) 


+ I 
This will add the number held in the second number of the stack, to 
the value held at the crldress en the top of the stack (Pronoonced 
"Plus-store"). 


e . g. 
4 HEX COOO +I <a>.> 


will add 4 to the value at COOO/COOl 
As will be shown later, this is of use when using variables in White Lightning. 


s: COLON OEFINITIONS 


These are the roost p:,werful and nost use:l forms of data structures in White 
Lightning, and are so called l:ecause they J::egin with a colon":" 


Colon definitions allow the creation of new Forth words based on previously 
defined words. 
They can be of any length, although carriage return must re 
pressed before a particular section excee:is 80 characters. 


The general fonnat is: 


: 
new-word 
w:>rdl "-Ord2. • • • • 
l«>rdn 
; 


All oolon definitions end with a seni-colon "·" 


If a word used in a oolon definition has not been previously defined, then an 
error will result. 


The rew-word is execute::l sinply by typing its narre and pressing ENim. 


e .g. 
$l.l)p()se ~ wish to define a new t«>rd to calculate the square of a given 
number. 


We oould 00 this by: 


: SQUARE I:E::IMAL rn . " '1HE SQUARE OF " COP • • " rs " J:XJP * . ; <rn> 


Here ~ have define:i a new t«>rd calle:i SQUARE 'Nhich will te called by 


number SQUARE <CR> 


e.g. 
9 SQUARE <CR> 


will result in: 


__ THE SQUARE OF 9 IS 81 


If 'E follow the cperation of the ¥10rd, we will see the changes in the stack: 
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'IDS 
OPERATION 
RESULT 
enpty 
9 
9 SQUARE 
9 
rn 
carriage return 
9 
'.!HE SQUARE OF 
9 
OUP 
9 
9 
. 9 
IS 
9 
OUP 
81 
enpty 
81 


and execution of SQUARE ends at the semi-colon. 


If ~ now wished., wie oould define a l'leW' \<oOrd using our v.0rd SQUARE. 


We are now going to discuss oontrol structures. It must re ranembe.red, that the 
control structures can ooly l:e incorporate:1 in colon definitions, or an error will 
result. 


6. CONTROL STRUCTURES 


llXJPS 


There are essentially o,,o forms of lcq> operation: 


(il 
DO ... LOOP 


(ii) 
DO ... +LOOP 


The first loop structure is used as follows: 


lbnit start ro ... 'Forth w::>rds' ••• IOOP 


The Forth words within the loc,p are executed until start = limit, incrarenting the 
start (or index) by ooe each time. Type: 


: TESTl 5 0 00 . " Forth " CT< llXlP ; <CT<> 
Typing in 'IFSl'l <rn> 
will print Forth 
Forth 
Forth 
Forth 
Forth 


The secorxl loop structure is used as follows: 


limit start IX> ••• 1 Forth w:>rds' incranent +LOOP 


The Forth w:>rds within the loop are executed fran start to limit, with the index 
l:eing increnented or decrerented by the value increrent. Try: 


: TEST2 5 0 00 . " HEW) " 2 +UXJP ; <CT<> 
Executing 'IB.ST2 will print HE.LID HELW HELLO 


Since the limit and. the index are held on the return stack, it would be useful if 
~ oould examine the index. 
Well, there are w:>rds to eh this: 
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'Ibis will o:::ipy the loop index: fran the return stack onto the data 
stack. 


J 
'lhis will push the value of the nested IOOP index to the stack. 


K 
This will p.1Sh the value of the double nested IOOP index: to the stack. 


Type: 


: 'IEST3 4 0 ID 4 0 ID 4 0 ID K J I • • • al IOOP IOOP LOOP 
<al> 


Executing 'IFST3 
will print: 


and so on. 


1 
1 
1 


1 
1 
2 
1 
1 
3 


7. CONDITIONAL BRANCHING 


Conditional branching must again be used only within a oolon definition and uses 
the form: 


IF (true p3Itl 


IF (true p3It) 
ENDIF 


(Forth WJROOl 


(Forth WJROO) 


ENDIF 


ELSE (false part) ... (Forth WJROS) ••• 


These oonditional statements rely on testing the top number on the stack to decide 
whether to execute the 'JRUE part, or the FALSE part of the oondi tion. 


If the top item on the stack is true Coon-zero) then the true part will be 
executed. 
If the top item is false (zero) then the true part will be skipped and 


execution of the false part will take place. 
If the ELSE part is missing, then 


execution skips to just after the ENDIF statement. 


There are several mathenat i cal operators 'Nhich will l eave either a true (non- zero > 
flag, or a false (zero) flag on the stack to be tested for by IF. 


These are: 


0( 
This will leave a true flag on the stack if the number on the top 
of the stack is less than zero, otherwise it leaves a false flag. 


e.g. 
-4 0< <al> 
will leave a true flag (non-zero> • 


To see this, type: 
• <OD 


to print the top numl:er on the stack, which is the flag. 
This will print 
1 
to shc>w a true flag. 


914 0< . <al> 


will print a O (false flag>. 
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O= 
This will leave a true flag en the t.op of the stack if the number on 
the top of the stack is equal to zero, otherwise it will leave a 
false flag. 


This will leave a true flag if the second number oo the stack is less 
than the top number, otherwise it will leave a false flag. 


e.g. 
40 25 < • <rn> 
will print O (false flag). 


If we lcok at the stack during this operation we, will see: 


Operation 


40 
25 
< 


TOS 
40 
40 25 
0 
enpty 


This will leave a true flag if the second number on the stack is 
greater than the top numrer, else a false flag will be left. 


e.g. 
40 25 > • <rn> 
will print 1 (true flag). 


: 
This will leave a true flag if the two top numbers are equal, 
otherwise it will leave a false flag. 


NCM' for sane examples using the oondi tional branching structures, type: ~ 


: 'lFSI'= = IF • " BY.m ARE EOOO. " ENDIF • " FINISHED " : <al> 


Na,/' key in two numbers follCMErl by TEST== and a carriage return. 


e.g. 
11 119 IBS'l'= <rn> 
This will print FINISIIF.D 


119 119 '.lES1'- <rn> 
will print IDT!! ARE = FINISHED 


New key in: 
: TFSTl= = IF • " E)JUAL " El'..SE • " lNEX)UAL " ElIDIF ffi • " FINISHED " 
<CR> 


New key in: 
249 249 TFSTl= <CR> 


this will print E)'JOO. 
FINISHED 


Try: 
249 248 TFSTl= <ffi> 


this will print lNEX)UAL 
FINISHED 


Notice hc7tl, the part after ENDIF W:lS executed in 00th cases. 


Two D'Ore loop structures will oow be discusse:i: 
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BEGIN 


BEGIN 


( Forth W)RC6) 


C Forth w:JRffi l 


UNTIL 


WHILE 
(Forth w:JRffi) 
• • • • 
REPEAT 


Using the EE3IN . . • . tNI'IL the value at the top of the stack is tested upon 
reaching UNTIL. 
If the flag is false CO) tlren the loop starting fran IEX:iIN is 


repeated. 
If the value is true (oon-zero) then an exit fran the loop occurs. 


Try typing the follCMing example: 


: (DUNI'-IXl,;N r::a::IMAL 100 IE,IN 1- 00P 00P • al O= UNI'IL • " [ONE " 
<al> 


Now key in: CDUN'IT:Om <al> 
This will print: 
99 
98 


3 
2 
1 
0 


I:ONE 


The EEX:;IN • • • \'lilLE • • • REPEAT structure uses the WHILE oondi tion to alort a loop 
in the middle of that loop. 
WHILE will test the flag left on top of the stack and 
if that flag is true, will oontinue with the execution of ....ords up to REPEAT, 
which then branches always (unconditionally> back to IB;IN. 
If the flag is false, 
then \\1-IILE will cause execution to skip the "-Ords up to REPFAT and thus exit fran 
the lCX>p. 


We will OCM construct a program to print out the cubes of numbers fran 1 upwards, 
until the cul:::,e is greater than 3000. 


The oolon definition oould te as follows: 


: CUBE r::a::IMAL 0 IE;IN l + <al> 
COP CUP CUP CUP * * IXJP <CR> 
3000 < WHILE • " 'IHE CUBE OF " <al> 
f;.;AP • • " IS " • al REPEAT <al> 
ffiOP ffiOP ffiOP • " ALL [ONE " al ; <al> 


You may get an error message "t-15G#4" appearing on the screen; this rreans that the 
-..;ord you have just created already exists. 
This is oot a problem since the new 
word will be created, and all actions referencing the w::>rd CUBE will be directed 
to the latest definition using that'. narre. 


NOol' run this i:J.t keying in: 


CUBE <al> 


and watch the results. 


Try to foll~ what is happening by writing down the values on the stack at each 
operation. 
If you are having any difficulty in doing this , t.~e stack values are 
sh(1,,l('l t:el~. 


STACK 


e;npty 
0 
0 
1 


OPERATION 


OB:IMAL 
0 
BB:;IN 
l+ 


OUI'Pllr I if any) 


( let us ro,,:, refer to the nurnter on the stack as N) 


N N 
DIJP 
N N N 
DIJP 
N N N N 
DIJP 
N N N N N 
DIJP 
N N N N' 
N N N3 


N N N3N3 
DIJP 
N N N3N33000 
3000 
N N N3flag 11 or OJ 


If '.!RUE: 


N N N3 
WHILE 


N N3N 
. " 'IHE CUBE OF 
'.!HE CUBE OF 


SiiAP 
N N3 
N 
• " IS 
IS 
N 
N' 
N 
CR 
carriage return 
N 
REPFAT 
I branch l:ack to l'fliIN l 


If FAISE: 


NN 
rn()p 
N 
mop 
e;npty 
rn()p 
• " ALL OONE " 
ALL OONE 
CR 


In fact, it is a good idea to dteck the stack oontents during the execution of any 
new Forth \!iOrd to nake sure that it is ...orking oorrectly. 
(Note that mop nerely 
clears the top numl:er fran the stack) . 


Finally, one extra construct has been added to circumvent the problem of deeply 
nested IF ••• THEN ••• ELSE structures. 
This is the CASE OF structure. It takes the 
general form : 


CASE nl OF (Forth Word) ENOOF n2 OF (Forth Word) ENOOF ••• ENOCASE 


For exarrple type: 


: 'IES1'4 CASE l OF • " FIRST CASE " ENOOF 2 OF • " SEX:'OND CASE " ENOOF 3 OF • " '!HIRD 
CASE " ENOOF ENOCASE ; <Cl!> 


New type : 


1 '.IEST4 CR 2 '.IEST4 CR 3 '.IEST4 CR <CR> 
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8. CONSTANTS AND VARIABLES 


White Lightning also allows you to define your CMn. oonstants and variables using 
the Forth w:>rds: 
= 
Vl\RIABLE 


When a ronstant is calle:3 tt>, this causes its VALUE to be pushe:l onto the stack, 
however, when a variable is called up, this causes its address to be p.ishea onto 
the stack. 
The Forth words ! and @ are u.se::l to roodify the rontents of the 
variable. 


A constant is define:l ~ using the form: 


value OONSTANI' narre 


and any references to the na:me will cause the value n to te I;XJ.t on the stack. 


A variable is defined using the form: 


value VARIABIB name 


and any reference to the narre will result in the address of that variable to be 
put oo the stack for further rranipulation using ! and @. 
It is essential that you 
realise the difference between the oontents and the address of a variable. 


New for SCJne; examples: 


64 aJNSTANI' R 1000 CDNSTANI' Q 
256 VARIABLE X 
0 VARIABIB Y 


R Q + 
X • 
X @ • 


will print the value of R + Q i. e. 1064 
will print the address of X, oot its value 
will print the value of Xf i.e. 256 
RY 
YX! 
4 X ! 


will store the value of R in the variable Y 
will store the address of Y in the variable X 
will store the value 4 in variable X 


BASIC Statement 


IETX=Y 
LETX=R 
LETX=4 
!ErX=X+S 


Forth Equlv,tent 


y@ X ! 
RX ! 
4 X ! 
5 X + ! 


OTHER COMMONLY USED FORTH WORDS 


LIST 
: This will list the contents of the screen number held on the top of 
the stack. 


e.g. 
6 LIST will list screen 6 to the screen. 
Note that if source has not been 


typed. into any of the screens, they will probably contain garbage. 


FORGET : This is used to delete pa.rt of the Lightning dictionary. 
Please note 
that rot cnly will the \<Qrd follc,.,,ing FORGE!' te erased, b.lt so will 
every \<oOrd defined after it! 


e.g. 
FORGE!' 'EXl-..MPLE will delete the v.0rd EX,n,MFLE (if it exists) along with any 
other ~rds defined after it. 


VLIST 
This is just typed in as a single v.0rd with no pararreters. It will 
cause a list of all the ""°rds defined so far~ pressing ERFAK 
(CAPS SHIFI' & SPACE as in B\SIC) will stop the listing. 


LOAD 
This will a:rnpile the source code that you have created using the 
editor into the White Lightning dictionary, to becone new Lightning 
i,.,,ords. 
Loo.ding will terminate at the end of a screen or at the 
Forth v.0rd ;S unless the "continue loading" \<K>rd -> is used. at the 
end of a screen. 
The idea of the screen will l::.ecane obvious in the 
next section on e1iting. 


USING THE EDITOR 


Generally Si,)Mking, nost users will want to use the Spectrum a:li tor to type and 
edit the source, bJt a full Forth line editor is incltrled for canpatibility with 
existing texts. 
The rraximtJTI length of any line is 64 characters. 
Any characters 
after this will 00 ignored. 


Line Editor 


Inclu:led in this version of White Lightning is a line erlitor to enable you to 
create source or text files. 
To facilitate text editing, the text is organised 


into blocks of 512 bytes, divided into 8 lines of 64 characters. 
Once the text 


has been erlited, it rre.y then be canpiled into the White Lightning dictionary and 
the text, if required, can be save:i to tape. 
The text is store:i in rrenory in the 


pages at C000 to F000, therefore, you can edit into screens 1 to 23. 
If the 


background facility is utilised, text is stored fran 0::00 onwards in screens 6 to 
23, and screens 0 to 5 cannot be use:i. 


Here i s a list of the editor o::rrmmds and their descriptions: 


H 
: 
This will Hold the text p:,inted to by the top number on the stack of 
the current screen in a temporary area kno.+1J1 as PAD. 


e.g. 
4 H will h::>ld line 4 of the current screen in PAO. 


S 
: 
Fill (Spread) the line number at the top of the stack with blanks, and 
shift dc,.,m all subsequent lines by 1, with the last line being lost. 


e.g. 
6 S will fill line 6 with blanks and nove all other lines dawn by one, 


pushing the last line off the screen. 


D 


E 


RE 
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Delete the line number held on the stack. 
All other lines are rroved 


up by 1. 
The line is held in PAO in case it is still needed. 


Line 7 cannot re deleted. 


Erase the line number at the top of the stack by f illing it with 
spaces. 


REplace the line number at the top of the stack with the line 
currently held in PAD. 


p 
Put the foll(7,,ling text on the line number held on the stack, by 
overwriting its present contents. 


JNSert the text fran the PAD to the line number held on the stack. 
The original and subsequent lines are m::>ved down ~ 1 with the last 
line being lost. 


EDIT 
Works just like the oorma.l Sinclair line editor. 
Also, it dcies an 
autanatic list and an autanatic flush. 
This is far and away the !::est 
way to e:Ht and the al:x:>ve are inclu:ie:l only for a::mpatibility 


CLEAR 


WHERE 


with existing Forths. 


Clear the screen numl::er held on the stack and rtake it the current 
screen. 


If an error occurs during the loading of White Lightning's text 
screens, then keying in mEnE will result in the screen numter and 
the offending line l::Eing displaye::1. 
You can now use the other editing 
cc.mrands to ed.i t the screen, or you nay rrove to another screen by 
elther LISTing or CLFARing it. 


e.g. 
15 LIST will rx:,w make screen 15 the current screen and will list the 


contents. 


In order to o:mpile this screen into the dictionary, it is necessary to use the 
word IDAD. 


WAD 


This will start loading at the screen number held on top of the stack and will 
stop at the end of the screen. 


If you wish to continue and IDAD the next screen, the current screen must end with 
-> 


1'his rreans "continue loading and interpreting". 


If you wish to stop the lOADing anywhere in a screen then use: ;S 


This JTBans "stop loadi ng and interpreting". 


At the end of every e::liting session, and before saving your text, it is necessary 
to FLl.SH the rraoory b.Jffers into the text area. 
To do this, just key in 


FLlEH <CR> 


Note that the EDIT cc:rrrrand does an autanatic FLl.EH. 


You can save your t.P.xt to tape using the Spectrum ' SA.VE' ccmnand. 
You must first 


enter BASIC by typing PR(X; 
<CR> • 


NcM for an example of 00W to e::lit a text file: 


The first step is to either LIST or CLFAA the screen about to be i,,.orkerl on: 
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9 CLEAR <CR> 


This sets the current screen to 9. 
To insert text use the EDIT camand. 
Type 0 
EDIT <CR> followed try the text below. 


'I'HIS IS H:M' 'ID PUT <CR> 


Then type l EDIT <CR> 


TEXT CN LINE 1 <CR> 


and s:> on, until you have entered.: 


0 IBIS IS IOI 'lO PUT <ffi> 
1 TEXT 00 LINE l <ffi> 
2 LINE 2 <ffi> 
3 AND LINE 3 OP IBIS OCREEN <ffi> 


9 LIST will produce: 


s::R # 9 
0 
IBIS IS IOI 'lO PUT 
l 
TEXT 00 LINE l 
2 
LINE 2 
3 
AND LINE 3 OF IBIS OCREEN 
4 
5 
6 
7 


To change LINE 2, type 2 EDIT <rn.> and then change it in the oormal way to insert 
' '!EXT 00' before 'LINE 2 1 • 
NOtJ type 9 LIST <ffi> to see the result. 
The e:litor 
ignores characters after the 64th character of the line l::eing edited. 


If you have a Sinclair printer connected., then it is probably worth defining a 
word to list screens to the printer. 


: SLIST PRT--00 l+ SWAP ro I LIST rn IOOP PRT-OFF ' 


To use the abc>Ve w:,rd, type the first screen number, last screen number, SLIST. 


e.g. 
6 9 SLisr <ffi> will list screens 6-9 to the printer. 


FORTH ERROR MESSAGES 


'£he following error nessages rray occur, and will be printed out in the form FRED ? 
MSG #0 
standing for ERED ? ERROR MESSAGE NlfflER 0 • 


# 0 
- 
this rreans that a w:,rd oould not 1::e found , or that a numeric conversion 
could oot take place. 


e . g. 
109Z <rn> 


# 1 
- 
this indicates an aupty stack and will be encoW1tered when trying to 
take nore values fran the stack than exi st. Try: 
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TESTl 
1000 
0 ro 
?STl\CK 
rnop IOOP 
: <rn> 
TESTl <ffi> 


?SIACK is a word which tests the stack for out ox oowds. 


# 2 - 
this indicates that either the dictionary has grown up to rreet the 
stack ( dictionary full) or that the stack has grc,..m down to rreet 
the dictionary. 


Try: 
'!EST2 
1000 
0 
CO 
?srACK 0 0 0 0 0 IOOP 
: <CR> 


TEST2 <CR> 


# 4 - 
this neans that you have redefined an existing \lriOrd using a new oolon 
definition 


Try: 
: ROT • 11 NEW IEFINITION " ; <CR> 


This is oot really an error since the new w:>rd is still valid, rut the old 
definition cannot te accessed unless you FORGE!' the new one. 


# 6 - 
this error nay occur when e:ii ting, loading or listing screens of data. 


Try: 
25 LIST <CR> 


This will prcxiuce MSG#6 aoo rreans you have tried to access a oon-existent 
screenful of rrerrory. 


# 9 - 
this indicates that an attempt \10.S rrade to clear sprite space of 
less than 2 bytes. 


t 10 - 
this indicates that one of the IDF.AL \NOrds made re ference to a sprite 
which did not exist, or that an attempt \10.S rrade to insert a sprite 
using !SPRITE with a number previously allocated to an existing sprite. 


# 17 - 
this will occur if you try to use a w::>rd in the 'imre:iiate' m:rle which 
should only te used during cx:mpilation, i. e. during oolon definitions. 
For a list of such i,,ords, refer to the glossary (words with "C" in the 
top right hand corner of the description). 


Try: 
CO <CR> 
IF <CR> 


# 18 - 
this cx:curs if a ""°rd rreant for execution only, is pit within a oolon 
definition (v.Urds with "E" in the top right hand oorner of the 


•description). 


# 19 - 
this means that a oolon definition contains conditionals that have 
not teen paired. 


e.g. 
a IOOP without a ro 
an ENDIF without an IF 


Try: 
: '!EST3 
ELSE 
• " WRON3 " : <CR> 


# 20 - 
this occurs if a oolon definition has not been properly finished. 


Try: 
: 'IES'r4 
I F 
. " OK " ; <an 
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# 21 - 
this rreans that you have tried to del e t e ~thing in the protected 
part of the Forth dictionary, e.g. 


FORGE:r 00 


22 - 
t.his implies the illegal U5e of -> when not loading text screens. 


23 - 
this happens when you try to edit a oon-existent line of screen data. 


Try: 
12 D 


SECTION3 


IDEAL 
by John Groat 


IDFAL has been designed to facilitate the manipulation of sprites and screen data, 
and with its 100 or so instructions, provides a ~ful and CXJT'lprehensive 
animation sub-language. 
Time should l:e taken to gain familiarity with the 


available o::mnands l:efore undertaking the first big project. 
Remember, that by 


using the colon definitions of Forth, new w::irds can very easily be adde:l to the 
language, Wilt £ran the existing Forth and graphics ¥10rds. 
Mastering this 
technique effectively will save a great deal of space, and in rrany cases, 
execution time. 


SPRITE 


A sprite is a software controllable graphics character. 
White Lightning supports 
up to 255 sprites with user selectable dinensions. 


SCREE.N WINDOWS 


A screen windQli' is a section of the screen defined by the four variables COL, RCM, 
Im and LEN. 
Colmins are in the range O to 31, ROlow'S are in the range O to 23, 


Heights are in the range l to 24 and Lengths are in the range 1 to 32. 
The unit 


for each is the character. 
CDL and 104 specify the p::,si tion of the top left hand 
corner of the window, with 0CM O at the top of the screen and OOL O on the left 
hand side of the screen. 
Im and LEN define the size of the wirn:lCM. 
To see an 
example type: 


SRO-J ! 6CDL ! 4fGl' ! 3LEN ! INW<On 


The wind.CM has been inverted to nark it out. 


SPRITE WINDOWS 


A sprite window is a section of the :sprite defined by the Fortb variables SX>L, 
~, Em and IEN. 
This time S::OL and ~cw specify the position of the t.op left 


hand oorner of the sprite wiruic,..;r. 
H:;T and LEN are again used to specify the 
dirnemsions of the wind.CM. 


SPRITE SPACE 


Sprite space is the area of rre:nory containing the previously definErl sprites. 
The 
variable SPST holds the address of the start of sprite space, so SPST should never 
J:e loaded with a new value unless a O)LO# cannand is l:eing executed, or you I re 
quite sure you know what you' re OOing ! ! 
SPND points to the first free byte after 
,sprite space. 
SPND should never l:e higher than FFFO Hex if routines are l:eing 
exe:::uted in Background. 


PIXEL DATA 


For those oot cquainted with the 1,r,,0rkings of the Spectrum screen display, each 
character on the screen is prcx:1uced as follows: 
each character cell is an array 


of 64 (8 by 8) pixels. 
A pixel is a 'dot' which can te INK colour or PAPER 
oolour. 
The bytes which define a particular character or block of characters are 
referred to as pixel data. 
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ATTRIBUTE DATA 


The oolour of the INK and PAPER in each particular cell, together with the 
!:RIGHTNESS aod FI.ASHit-li attributes of the character are controlled by a seperate 
byte. 
The bytes which define the attributes of the block of characters are 
referred to as A..ttribute data. 
Pixel data and Attribute data are frequently 
treated as seperate entities. 


SCREEN OPERATIONS 


Often, it is required to carry out an cperation such as a scroll or a reflection, 
on one parti cular section of the screen. 
Four variables are use:1 to define a 
screen wind.CM, these are O)L, R0-1, I-Cl' and LEN. 
The co-ordinates of the top left 
hand corner are held in COL and RCW, where OOL is rreasured fran the left and RCM 
fran the top. 
Both values are in diaracters. 
lCl' and IEN are the dimemsions of 
the wind.CM. 
OOL + LEN must be in the range l to 32, and RCW + fill must re in the 


range 1 to 24. 
CO'rmands in this group are postfixed with a "V", e.g. \'IU.lV, INW, 
MIRV. 


SCREEN/SPRITE OPERATIONS 


These are cperations between the screen and a sprite. 
The dirrensions of the 
sprite are used as the dirrensions of the screen window, and CDL and R:::M are used 
to give the ex>-ordinates of the top left of the windcM. 
If\ the window overlaps 
the edge of the screen, the ccrrrnand will not execute. Typical o::mnands in this 
group are the Pill's and GETs, which rrove sprites between the screen and rrarory. 
Camands in this group are p::,stfixed with an 
115", e.g. PUI'BLS, GE'IXRS. 


SPRITE OPERATIONS 


These cover rrore or less the sarre o::mnands as the screen operations, but this t.i.ne 
a cm,plete sprite is used instead of a screen window. 
The only paraneter required 
is the sprite m.1nber stored in SPN. 
Catmands in this group are postfixed with an 


"M", e.g. WRR4M, ATI'UPM. 


SCREEN/SPRITE W INDOW OPERATIONS 


These are q>erations tetween a screen window and a sprite window. 
As tefore, RCW, 


COL, Em and LEN define the screen window, rut this time, S::OL and S:«:M are used 
to define the [X>Sition of the window within the sprite. 
S:::OL and SRCM are 
measured in characters, SR™' £ran the top and S:::OL fran the left. If SR0'1 + Em 
is greater than 24 or the sprite height, or if 9:X>L + LEN is greater than 32 or 
the sprite width, the ccrrrnands will not execute. 
These cxmnands are postfixed 


with an "S", e.g. ~'ITS, PK>RS. 


SPRITE/SPRITE WINDOW OPERATIONS 


ll\ese are cperations between a whole sprite and a sprite window. 
The M> sprite 


mnnbers are held in SPl (the wTIOle sprite) and SP2 (the sprite which contains the 
window). 
The dimensions of the window are the dimensions of the sprite whose 


numter is held in SPl. 
The [X>Sition of the window in the sprite \io'hose nanber is 
held in SP2 is specified by 9:XlL and SRCW. 
Ccrrmands in this group are postfixed. 


with an "M", e.g. QIU\.TIM, :EWNI:M. 
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SPRITE/SPRITE OPERATIONS 


Tl'ese are operations between sprites which usually have the sane dimensions, or, 
as in the case of the SPIN a:mnand, transposed dinensions. 
SPl and SP2 
hold the 
sprite numbers. 
Ccmra.nds in this group are (X)Stfixei with an "M", e.g. OOPORM, 


SPI!M. 


DUMMY SPRITE 


A dmmy sprite is a sprite Mlich does mt oontain data for display. It may be 
used, for instance, to store a ma.chine cxrle subroutine, an array, or rraybe a 
oollision detection sprite. 


IDEAL VARIABLES 


The IDEAL sublanguage uses 27 variables in all, these are: 


VARIABLE 


ROW 


LEN 


COL 


HGT 


SROW 


SCOL 


NPX 


SPN 


SP1 


SP2 


USE 


Used to h::>ld the ITM (Y exrord) in characters, measure::1 
fran the top of the screen (0-23). 


Used to h:>ld the width of the current screen window 
(1-32) or the width of the sprite being defined (1-255). 
Units are characters. 


Used to OOld the oolllllrl (X co-ord) in characters, rreasured 
fran the left of the screen ( 0-31) . 


Used to OOld the height of the current screen window 
(1-24), or the height of the sprite being defined (1-255) . 
Units are dlaracters. 


Used to h::>ld the rrM (Y co-ord) within the sprite \oi'hose 
number is held in SP2, measured fran the top (O-(lCI'-1)). 
Units are dlaracters. 


Used to OOld the colunn (X co-ord) within the sprite 
whose number is peld in SP2, rreasure:l fran the l eft 
(0-(IEN-l) ). 
Units are characters. 


Used to OOld the size and direction of vertical scrolls. 
Positive scrolls are up.,;ard and negative downward. 
Units are pixels and not characters. 


Used to OOld the sprite number for those ..ords which 
operate on only one sprite (1-255). 


Where c:perations involve a sprite and a sprite window, 
SPl holds the number of the sprite which does oot contain 
the window (1-255). 
Where a sprite is to be spun into a 
second sprite, SPl holds the number of the first sprite 
(1- 255). 


Where cperations involve a sprite and a sprite window, 
SP2 holds the number of the sprite which does contain 
the window (1-255). 
Where a sprite is to be spun into a 
second sprite, SP2 holds the number of the second sprite 
(1-255). 
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SPST 
Used to hold the start crldress of sprite space. 


SPNO 
Used to hold the end of sprite space, i.e. the first free 
byte after the last sprite. 
This is the address of the 
foreground scrolling b.iffer. 


SLEN 
Used to hold the length of sprite space to be cleared 
by the O'.lLD# =irnand. 


MLEN 
Used to OOld the size and direction of the relocation. 
A p::>sitive value relocates sprites to higher rreoory and 
a negative value to l~r rrerrory. 


SPTR 
On return £ran the TEST ccmnand, SP'IR p:>ints to the start 
of the sprite. 


OPTR 
On return fran the TEST cxmnand, CP'IR p::>ints to the start 
of the pixel data. 


Alternate Variables 


Eleven of the previously listed variables are replecated for use by the tackground 
program C see Foreground/Background) . 
These are ~ 
1 , O)L' , LEN' , a:;T 1 , 
NPX • , 


SPN', SPl', SP2', SR.CW', S:::OL' and SPND'. 


When a w:>rd is executed in tackground, the eleven alternate variables are 
autanatically switched with the eleven foreground variables; when execution is 
canplete, the variables are switched again to restore them to their fonner state. 


SupfX)se, for example, that the background program is to scroll left 1 pixel with 
wrap (~lV), with an area of screen 6 characters wide and 4 characters high, with 
top left ro-ordinates rcM = 5, colunn = 7. 


No< type the following: 


CLS 6 LEN' ! 4 H:;T' ! 5 Ra-1' ! 7 CDL' ! ' WRLlV INT--0:-1 <CR> 


The window is rt:M scrolling bJt you can't see it, tecause there is oo data in the 
windc,w-. 


Type VLIST <CR> and watch the data as it scrolls through the window. 
The data in 


the window will be slanting to the LEFT, tecause the foreground program was 
scrolling up at the same tirre as the background program scrolled left. 


Lea.ving the background program running, type: 


10 IEN' I <CR> 


and the wiildcM will widen. 


Type: 


INI'-OFF ' ~8V INl'--0:-1 <CR> 


and the screen will scroll to the right, this tirre moch rrore rapidly. 
Now type: 


to halt the backgroUD:i program. 
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In the above example we; set l::ackground variables £ran foreground. 
If we we;re to 


set the l::ackground variables actually in the te.ckground program, then foregrourrl 
and tackground variables "'-Ould already have teen switched before execution. 
To 


set up the sarre windows, we; "'-Ould rK:M have to use ~, (l)L, lGl' and LEN arrl oot 
RCM 1 , OOL', Im' and I.EN'. 


To define a 't,Ord to 00 this, type: 


: FRED 6 IEN ! 4 Em ! l RCM ! 2 OOL 
WR.Ll.V ; <CR> 


To run "FRED" in te.ckground, type: 


I FRED INI'~ <CR> 


Since the variables were this time l::eing assigned values in the background program 
itself, the alternate variables set ~s t:eing accessed with the oonnal names. 
Now 
type: 


INT-OFF FORGET FRED <ffi> 


to halt the background program and clear the definition. 


Operating in this ~y, a word will work in fore::;,round or 1:ackground without any 
need to dtange variable nanes. 
The alternate variables are only used directly by 


a foreground program that is IaJUire:1 to change ba.ckground. variables, or a 
background program that is require:1 to change foregrourrl variables. 
If the 


previous example is a little oonfusing at first, carry out your own 
experinentation until it becnres clear. 


ERRORS 


The graphics cx:mnands do oot in many cases provide the user with error rressages, 
rut instead, if an attenpt is rrade to execute a cx::rmand which is oot p::>ssible, for 
instance scrolling a screen windc:M which lies partly off the screen, the o::mnand 
will simply oot execute. 
This does have the crlvantage that the user is freed fran 
testing e:lge oonditions, b.lt does rrean that a little extra care needs to l::e 
exerci sed. see the words AO.JM and AOJV. 
Er rors are generate:l i f an at tempt is 


made to access a non-existent sprite, or to insert an already existing sprite 
using ISPRITE. 


SPRITE AND BUFFER ORGANISATION 


Before discussing the sprite manipulation cx::rmands in detail, it is w:,rth 
describing the organisation of sprites in sane detail. 
The user does oot neErl 
this infomation, rut it is tm.de available for interest and an overall 
appreciation of the language structure. 


Sprites are stored as one contiguous block of data whose start crldress is held in 
the variable SPST. 
The first free byte after the final sprite contains a zero and 
this ad.dress is held in the variable SPND. 
The format of each sprite is as 
follows: 


First byte 


Secom and 
third bytes 


Holds the sprite number which must t:e in the range 
l to 255. 


Hold the a:idress of the start of the next 
sprite. 
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Fourth byte 
Holds the width of the sprite in dlaracters (1 to 255). 


Fifth byte 
Holds the height of the sprite in characters Cl to 255). 


B*height*length bytes 
Pixel data. 


Height""length bytes 
Attribute data. 


This rreans that the total space allocated to each sprite is 9*height*length+5 
bytes. 


Sprite numbers do oot need to run sequentially, but the earlier a sprite is 
defined, the rrore rapid its access. 


LOAOING SPRITES FROM TAPE 


Sprites save:i to tape using the developnent ooftware, can t:e loade:l into the main 
pr0:1ram at the start of the session when the "IDAD SPRITES Y/N" pranpt appears. 
If sprites are load.al in this rranner, the sprite data, together with the necessary 
pointers, will te loade:l. 
SPST and SPND are autanatically set and the sprites 
will be ready for use. 


If sprites are sava:1 and later loaded £ran White Lightning, SPST and SPND will 
need to l:e set by hand. 


THE BUFFER 


When vertical scrolling takes place, be it for pixel data or attributes, with or 
without wrap, data has to l:e tanporarily stored for later retrieval. If a 
vertical scroll is executed by the foregrourrl pr0:1ram then the bJffer is p:,inted 
to by SPND, so the space imrediately above sprites is used. 
When the sprite 


developnent software is used., a pranpt is issued at the start of the session, 
which asks the user whether or oot bJffer size should t:e changed. 
If the bJ.ffer 
size is oot changed then it renains 256 bytes long. 
The user can enter a larger 
or ffiBller value if preferred, though the default value of 256 will cover rrost 
eventualities. 


Scrolling attributes uses ooe byte for each oolmn of the width, scrolling pixel 
data uses one byte for each ool\Jlll of the width, multiplied by the number of 
pixels being scrolled (the value held in NPX, see vertical scrolls}. 
The b.Jffer 


space need ooly te large enough to accaoodate the largest scroll, as foregro\100 
scrolls will not take place simultaneously. 
Supp:,se a sprite or screen window' 8 
characters high by 4 characters wide is to te scrolled by 10 pixels. 
(The 


direction, i.e. the sign of NPX does oot natter). 
The space required is 4 * 10 = 


40 bytes. If you find at sane later stage that you have rot all"""'1 enough buffer 
space, you can always relocate sprite space cJcMt,.ward and likewise, if you have 
rrore than you nee::!, you can relocate upwards. 


BACKGROUND SCROLLING 


When programs are executed in background (see Foregro\100/Backgrourrl) it is risky 
to share a c:x:mron scrolling b.Jffer, since the background program oould execute 
while the foreground program is using the b.J.ffer. 
For this reason, a second 
l::uffer pointer is used for background scrolling. 
The variable OOlding the aidress 


of the background bJffer is SPND'. 
When White Lightning is first entered, SPND' 


points to the 256 free bytes in the printer buffer at decimal 23296. 
'!be user can 


n-ove this buffer by changing the value held in SPND'. 
It is rot a !:ad idea to 
allocate enough b.Jffer space, for l::oth forS3"round and background scrolling above 
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sprite space and assign SPND' to i;:oint to the space after the for83rourrl tnffer. 
Sq:,pose, for exaI'Rf¥.e, the for83rourrl program requires 200 bytes and the background 
300 bytes, with the b.Jffer currently set to 256 bytes. 
500 ti;tes are needed in 
all, oo sprites need to be relocated down by 500 - 256 = 244 bytes. 
Type: 


-244 MLEN I REWCATE <CR> 


Note that MLEN is J'lOW' negative since relocation is ~ward. SPND' should be set 
200 bytes into the b.Jffer to leave space for the foregroun:l data. 
To oo this 
cype: 


SPND @ 200 + SPND' ! <CR> 


If memory is really tight and the b.Jffer has to be shared, 
then the backgroun:l 
program can t:e tenp:>rarily disabled using DI b.lt as soon as the vertical scroll is 
executed, an EI nrust be executed to re-enable the background program. 
If, for 
exanple, a screen windcw 12 characters wide and 4 characters high is to be 
scrolled vertically by 8 pixels with wrap, and the backgroun:l program is to be 
inhibited, type: 


0 0 Kr 8 NPX ! 12 IBN ! 4 11,l' ! 4 ClJL I 4 IOI ! DI ICRV EI <CR> 


It is best to re-enable the background program as soon as p::,ssible, preferably, as 
above, the next 'WOrd. 


Until you get used to the package leave the Wffer s as they are on entry to White 
Lightning. 
Use !SPRITE and OSPRITE, and oot SPRI'IE and WIPE to define new 
sprites. 
The ooly time you really need 'WOrry alx>ut changing tnffer sizes or 
p::>sitions is ""1en you have a dire need to save a few extra bytes. 


IDEAL MNEMONICS 


To get the best out of the White Lightning package , please read these next 
sections carefully and oote the paraireters. 
The w::>rds have been selected so as to 
be as rmenonic as p:,ssible . 
'lb help yourself tecare aquainted with the language, 
it is ,;,,orth ooting the following: 


1. 
wards W'lich involve only the screen are p:,stfixed with "V" for "Video 
Operat i ons". 


2. 
Words which i nvolve ooly c:perations oo or between sprites, are postfixed 
with "M" for ''Meoory Operations". 


3. 
Words which involve operations between the screen and sprites are postfixed 
with "S" for "Screen/Sprite'' operations. 


4. 
BLS implies that data is t:eing "Block Shifted" to a destination and will 
replace whatever \,,8.S there . 


5. 
CRS implies that data is t:eing "Shifted and CR'erl" so the destination data 
will be CR 1 ed with the source data. 


6. 
NCS implies that data is to t:e "Shifted and AND' erl". 


7. 
XRS implies that data is to t:e "Shifted and XOR'erl". 


B. 
AT1' implies that the operation is on attribute data. 
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9. 
~ irrplies that the data will re scrolled with wrap. 


10. 
s:::: i.rrplies that data will re scrolled without wrap. 


11. 
GN "Get Window" in-plies that data is reing noved fran a window into a 
sprite. 


12. 
IW "Put Window" implies that data is b=ing p.1t into a windCM fran a sprite. 


13. 
OOP i.rrplies an cperation b=tween b.o sprites with the same dimensions. 


The !:est W3.Y to tecare familiar with the language is to use it! 


There are also sane general IX)ints w:irth ooting. 


GENERAL POINTS 


1. vertical scrolls will require sane b.iffer space at the end of sprite space, 
so rrake sure that either you have se:t up sprite space with the developnemt 
package ( the default of 256 is usually crlequate), or that at least one OOLD# 
has teen executed to rrake space. 
The space required for a scroll is 
obtained by multiplying the width of the sprite, by the number of pixels 
to be scrolled. 
Horizontal scrolls do oot require b.Jffer space. 
When 


White Lightning is first Loaded without sprites, a OOLO# is autcmatically 
execute:! and sets the ooffer to 256 bytes. 


2. 
All attribJte scrolls are "with wrap". 


3. 
COnnands prefixed with GET or PfJI' are operations between a whole sprite 
and a screen windaw. 
These are very fast and can be rrade even faster 
by suppressing the rroverrent of attribute data, if its transference is 
oot required. 
To suwress attribute data use the word AT:t'OFF. 
If you 


wish to switch data flow back on at a later stage, use ATION. 
The switch 
remains in its state until changed by the execution of ooe of these 
two w:irds or the execution of a ....ord ~inning with GN or IW and ending 
with S (group 2 GETS and Pm'S). 
NEVER assurre the state of the switch 
at the start of the program: 
ooe of your first words at the beginning 
of your program should be ATION or ATrOFF. 


4. 
If a sprite is dynamically allocated space at runtine it will probably 
contain garbage in its pixel and attribute data, so b:>th will need to be 
set tt'· It is all too easy to forget the attributes. 


5. 
Sanet.ines the dynamically created sprites will oontain zeroes; if you set 
up the pixel data and forget the attribute data then execute a PUl' to 
the screen with the attribltes oo - a black rectangle will appear. See 
Slfl\M. 


6. If you want to wipe a sprite off the screen but not affect any other 


pixel data within its screen window, use POl'XRS. 
Remember, though, that 


if you have carried oot any c:perations oo the original sprite since 
doing the original rorer.s or PlIDCRS it may not w::>rk. 


7. 
If you W3.Ilt to leave a sprite oo the screen tut clear all other pixel data 
in its screen window use PU'INIS. 
Again, te sure that no intermediary 


c:perations have taken place. 
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8. If you wish to RJT a sprite ooto the screen over the top of the existing 
data in the window, then you should use Pl1IORS. 


9. 
Points 6-8 apply to cperations in rrerory, although the words used are 
of oourse different. 


10. 
The l:est way to get to know the POTs and GETs is to experilrent with them; 
you will soon realise h::,,,., to rrove sprites. 
For those of you not yet 
familiar with \otlat "AND", "CR" and "XOR" rrean, note the following: 


a) If o,,o sprites are AND'ed, then only those pixels set in 00th will 
remain set when the sprites are AND'ed together. 


b) If t"-0 sprites are CR 'e:1, then all those pixels set in either sprite 
will be set in the result. 


c) If ti,,,u sprites are }IJ)R'e:l, then all those pixels set in either 
sprite will l:e set in the result, h.It this time, all pixels where 
00th were set will rrM l:e reset. 


d) All "Block Shift" a::mnands will destroy whatever was previously 
in the window. 


11. It is possible to set up "rrasks" in durrrny sprites and use the l:oolean 
operations CR, XOR and AND to rrove windows around etc. 


12. 
If you wish to make sarething appear at lightning speed, leave the data 
on the screen and fill the window with zero attributes or attributes with 
the same: INK and PAPm colour. 
To nake the sprite appear you reed only 
cbwnload the attributes using PWATI'S; to make it disappear use 
PWATI'S again, b.lt this tine, download stored att ributes with the sarre ink. 
and i;:,aper oolour, or use SETAV. 


13. 
It is r;:ossible to use the 'IBST ccrmand to gain direct access 
to the attributes in the sprite nerory. 
They are located at DPIR+ 8--r.E'.N*lm 
and can be easily block fille:l. 


14. 
Meat animation routines use only the variables: 


Icr 
Height of window 
I.EN 
Width of window 


(l)L 
Screen colurm of top left character 
0CM 
Screen row of top left character 
S:OL Sprite colunn of top left character 
SRCM 
Sprite row of top left character 
SPN 
Sprite number 
SPl 
Nmnbe.r of first sprite in a double sprite cperation 
SP2 
Nunl::er of second sprite in a double sprite cperation 


Columns are rreasured in characters (8 pixels by 8 pixels) and are counted 
fran the left, O to 31. 


RCJ,,1S are rreasured in characters and are counted fran the top O to 23. 


Ra:nember, never change a variable wiless you nee:3 to, they are not 
reset bet~n instructions (with the exception of AD.JM and AOJV) , and 
you can always write your cede to order the operations in such a way as 
to minimise the resetting of variables. 
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15. 
If a w:.:,rd ending in V {screen q;:,eration) does not execute, it is alm:>st 
always tecause the window you have defined does not lie wholly on the 
screen. 
That is to say, that OOL + LEN is oot in the range 1 to 32, or 
RCM + 00T is oot in the range 1 to 24. see ADJV. 


16. 
If a w:.:,rd ending in S {screen/sprite operation) does not execute, then 
again, it is alm:>st always because the sprite width + (X)L is not in the 
range 1 to 32 or the sprite height + RCM is not in the range 1 to 24. 
See ADJM. 


17. 
If a w:.:,rd ending in S that is also a window cx:mnand ( secx:md letter W) 
does not execute, it may te for the reasons outlined in 16, or it may te 
that S:OL + LEN or SR<Nl + ICr do oot lie within the width and height of 
the sprite oontaining the window. 


18. 
If a w:.:,rd ending in M that is oot a window ccmnand does not execute, 
the sprite probably d:>es oot exist; if it is a window a:mnand, then it 
is likely that the width of the first sprite + RCM or the height of the 
first sprite + OCOL do not lie within the width and height of the 
sprite oontaining the window. 


19. 
Renemter that the SPIN o:mnand reeds a second sprite to rotate into, 
and that its dimensions should be the reverse of the sprite to te 
spun. 
For real speed, it is test to store the sprite in each of its 
4 orientations. 


20. 
If you wish to 00 a vertical mirror, just SPIN, do a horizontal 
mirror, and SPIN back. 


21. 
It is goal p:,licy always to make the sprite one character higher and 
wider than the graphic character itself; this will enable you to scroll 
the character within the sprite and give pixel resolution when using 
the PITT ccmnands. 


22. 
If mem:::,ry pennits, it is a gcx:xl idea. to keep a "back-up" of each sprite 
held under a different number, so that if an error is rmde and a sprite 
corrupted, it can t:e oopie::l back fran the cx:,py. 
They can always be deleted 
fran the final program. 


23. 
Never execute the N&i or CLFAR cxmnands when in BASIC. 


24. 
If a sprite driven under interrupt disappears fran the screen or 
flickers, it is probably a timing related problem and re-ordering 
the o:xie will alm:)st certainly solve the problem. 


25. 
Screens can re rroved tl) and down naoory using the DOVE \<oOrd. :Each screen 
occupies 512 bytes and the addresses are listed in Table 1, the Table 
of Screen Ad:rresses. 


26. 
If you are using the Background facility, the top 16 C¥tes of RAM will be 
use:l, so any data stored there will be corrupted. 
To avoid this, rrak.e 
sure you have enough scrolling OOffer and keep the tq:, of sprite space 
below 65520. 


27. 
If you execute SETAM or SEl'AV in background, set the FIASH attribute 
in the background program. 


28. 
If you wish sprite space to "grCM" upward use SPRITE and WIPE, otherwise 
always use !SPRITE and J:SPRITE for sprite allocation. 


29. 
BAD RAMIOP error, usually neans you have not RESERVED sufficient 
space for your Bl\SIC program. 
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IPRITE UTILITIES 


All the sprite utilities described in this section are available at run-time, l:ut 
we strongly reccmrend that all sprite allocation is undertaken at the sprite 
developrent stage to save laboriously reloading sprite data if an error is made at 
run-tine. 
They are provided for advanced progranming applications only and should 
never te executed in background. 


COLO cl< 


This cx::mt\:lild sets the end of sprite space p::>inter SPND, to the value in SPST, the 
start of sprite space pointer. It then clears neoory above SPST. 
The size of the 


mem:::>ry cleared is specified in SLEN. 
Fach tine a sprite is allocated space using 


the SPRITE CXJ111\:li1d, SPND is l.{Xiated. 
Vertical scroll data (pixel and attribute) 


uses the space i.nmediately above SPND so a roLD# is necessary at sore stage te-fore 
executing the o:mnands. 
The arount of data required is given ~ the prcxiuct of 


the sc:"roll width and the number of pixels scrolled. 
sprites are stored in the 


follCMing form3.t: 


First t,,,te is the sprite number 
(1 to 255) 


Se::ond and third bytes OOld the oodress of the next sprite in neoory. 
Fourth byte is the sprite width 
U to 255) 


Fifth t,,,te is the sprite height 
Cl to 255) 


The rext 8*height*length t,,,tes hold pixel data. 
The final height*length t,,,tes hold the attributes. 
Therefore, each sprite requires 9*height*length+5 bytes. 


It should 1:e noted that sprite numbers need oot te allocated in any particular 
order. 
The test [X)Sition ear sprite space is at the top rf· rrenory and it is oot 
difficult to calculate space required, although the devnloprent package does this 
autaM.tically. 


To calculate the total sprite space that will 00 used, use 9*length*height+5 for 
each sprite and then add b.lffer space for vertical scrolls, 256 should te 
sufficient for nost applications. 
This total should te assigned to SLEN. 
SPST 
should then l:e assigna::1 with 65520-SLEN. 


St:pp:>se you wished to allcx:ate space for 10 4 by 4 sprites, 3 8 by 6 sprites and a 
5 by 4 sprite. 
Supp:,se also that a 4 pixel scroll will l:e re:Juired for a 4 


character wide sprite, and a screen window 9 characters wide will need. to te 
scrolled 3 pixels. 
The 8 by 6 sprite is also to te rotated. 
The following 


proce:luz;e to calculate sprite space is required. 


10 
4 by 4 sprites require 
3 
8 by 6 sprites require 
1 
5 by 4 sprite requires 


10*(4*4*9+5) = 1490 bytes 


3* ( 8*6*9+5) = 1311 bytes 
1*(5*4*9+5) = 
185 bytes 
IDrA.L = 29 86 bytes 


The 4 character wide sprite scrolling 4 pixels ~uld require 16 bytes. 
The 9 character wide screen window scrolling 3 pixels i,.uuld require 27 bytes. 
If ~ allow 27, then this will cover l:x:rth eventualities and we can forget the 16 
bytes for the first case. 
'11'.YrA.L = 27 bytes 
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A dunmy sprite 6 by 8 is also required for the rotation so: 


1 
6 by 8 sprite requires 


So the overall total is 


1*(6*8*9+5) = 437 bytes 


2986+27+437 = 3450 bytes 


If this is to l::e located at the top of rrarory, then SPST will need. to re set to 
65520 - 3450 = 62070. 
Note that rremocy 65520 to 65536 is used foe l:ackgrnund 


applications. 


In this case you ~uld use the following: 


62070 SPST ! 3450 SI.EN ! O)LD# 


SPND will l::e autanatically set to 62070. 


If all this seem.s a bit o:mplicated, don't ~rry. A far simpler way of setting ui 
sprites is to use the !SPRITE and CSPRITE a::mna.nds described later in this 
section. 
You won 1 t even nee:J. to execute a a)LD# carmand. 


SPRITE 


Ooc:e the sprite space has teen cleare:J., the sprites themselves can l::e set up. 


Parameters 


SPN 
001' 
LEN 


Camrurl 


SPRITE 


Note: 


Use 


NLJnber of the sprite to be set up 
Height of the sprite in characters 
Width of the sprite in characters 


Action 


The five byte leader is set up and SPND Mjuste:J. 


If space is dynamically allocated to a sprite, the sprite will oot necessarily be 
initialisa:l and rrey oont.ain garbage. 
If a sprite is being set up at run-t.i.rre, be 


sure that sufficient rrerory is available. If a sprite number is given that has 
been previously used, the old sprite is destroyed and recreated with the new 
dimensions. 
If sufficient rreoory is oot available, then either an old sprite can 


be destroyed or the whole of sprite space can be relocated dc,.,mwards if space is 
available. 
Moot users will probably oot use the SPRITE ccmnand, but instead, will 


use the far Sinpler !SPRITE ccmnand. 


WIPE 


This cxmnand will destroy the sprite whose nwnber is held in SPN, relocate the 
sprites above it oownwara, update the variable SPND (rrarking the end of sprite 
space) and leave the particular sprite number free for reallocation. 


ParMeter 
Use 


5PND 
The number of the sprite to be wiped 
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Ccmnand 


WIPE 


RELOCATE 


Action 


Destroy a sprite and adjust llBllDry 


An alternative rrethcxi for creating rrore space to define new- sprites, is to 
relocate sprite space downward. 
Only one parameter is require:l, MLEN. 
A p:,sitive 
value in MLEN will relocate sprites to high trem:>ry and a negative value will 
relocate them downward. 
All p::,inters are reset. 


Parameter 


MI.EN 


Carmand 


RELOCATE 


Exanple: 


Use 


Size and direction of relocation 


Action 


Relocate all sprite data and reset p::,inters 


If space for a 4 by 4 sprite is to re nade and the existing b.Jffer space 
rraintaina:1, the sprites ....ould need to be relocated downward ~ 4*4*9+5 = 149. 
To 
do this use the following: 


-149 MLEN ! RELOCATE 


TEST 


For crlvancecl applications there is a ccmnand to interrogate sprite details. 
SPN 
is loada:1 with the number of the sprite to be interrogated, and after execution, 
the fol1C1,rr,1ing parameters will be set: 


Em 
will OOld the height of the sprite 
lEN 
will OOld the width of the sprite 


SPTR will hold the address of the first 1:1.{te of the sprite header 
DPIR 
will hold the address of the first byte of the pixel data 
SIZE will hold the arrount of rrerory occupied by the sprite 


In order to calculate the start of attribute data, use Dl?I'R+S*HGT*LEN. 
Note that 
a::;T, LEN, SPTR and DP'IR will all be zero if the sprite wasn't fourrl. 


A true or false flag is also placed on the stack . 
True means the sprite exists 
and fal se rreans it doesn • t . 


Example: 


To see if sprite 34 exists, and print i ts dirrensions if it does - use: 


34 SPN ! TES'r IF H:;'r ? LEN ? CR ENDIF 
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ISPRITE AND DSPRITE 


If sprites are located at the top of rreoory, then !SPRITE and OOPRITE can be use:i 
to create and destroy sprites without the need for any canplex calculations. 
!SPRITE will insert a sprite at the top of rrarory, maintain the bJffer space and 
autana.tically rel ocate the rest of sprite space downward, 
DSPRITE will destroy an 


old sprite and relocate sprite space lJl?Wclrd, 
The easiest way to use this package 


is to leave the b.lffer space as it is, then just use !SPRITE and OSPRITE to rn.FATE 
and DESTROY sprites. 
SPRITE, WIPE, OOLD# and RE.r..O:ATE are for a:ivanced 
applications where sprites are created during program execution. 
If a "ZAPPED" 
program ~re to execute ISPRITE the sprites ~uld extend downwards and oould 
overwrite the object cxxle of the main program which lies just beneath SPST. 
I f a 


program runs before being "ZAPPED", tut the final run-time version crashes, this 
is where to look ! 


Pararreter 


SPN 
fGT 
IBN 


Camand 


!SPRITE 


Pararreter 


SPN 


Camand 


DSPRITE 


Note: 


Use 


NLinber of the sprite to l:e inserted 
Height of the sprite to l:e inserte::l 
Length of the sprite to be inserted 


Action 


Create rEW sprite and OOjust neoory 


Use 


NLTilber of sprite to be inserted 


Action 


Wipe old sprite and adjust rrenory 


Be sure sufficient nerory is available l:efore executing !SPRITE. 
SPST holds the 


start; after execution, SPST will tecare SPST - 9*1rn*LEN-5. 
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SCROLLING 


SCREEN SCROLLS 


The OOrizontal screen scrolls are ~ 1, 4 or 8 pixels, left or right and with or 
without wrap. 
The vertical scrolls are slightly rrore flexible. 
The variable NPX 


is loaded with the number of pixels to be scrolled, positive for q:,ward novanent 
and negative for 'ck:>wnward rrovement. 
In each case, a screen window has to l::e 


defined. 


Horizontal Scrolls 


Pararreter 
Use 


CXJL 
COlum of the left hand e:lge of the window C0-31) 
1'CM 
Re>o1 of the top edge of the window C0-23 l 
IBN 
Width of the window Cl-32) 
!ill 
Height of the window ( 1-24 l 


CCXrmand 


WRL1V 
WRR1V 
SCL1V 
SCR1V 
WRL4V 
WRR4V 
SCL4V 
SCR4V 
WRL8V 
WRRBV 
SCLBV 
SCRBV 


Note: 


Action 


Scroll left 1 pixel with wrap 
Scroll right 1 pixel with wrap 
Scroll left 1 pixel, 
no wrap 
Scroll right 1 pixel, 
no wrap 


Scroll left 4 pixels with wrap 
Scroll right 4 pixels with wrap 
Scroll left 4 pixels, 
no wrap 
Scroll right 4 pixels, 
no wrap 
Scroll left 8 pixels with wrap 
Scroll right 8 pixels with wrap 
Scroll left 8 pixels, 
oo wrap 
Scroll right 8 pixels, 
no wrap 


Befor e executing any of these ccmnands, the winda,,, needs to l::e set up using the 
four pararreters above. 
If the ccrmand does oot execute, it is likely that part of 


the window does oot lie oo tl1e screen. 
OOL + LEN should t:e in the range 1 to 32 
and IEN + l-m should t:e in the range 1 to 24. 


Exarrple, 


To see these cx:rmands \loOrk, it is a good. idea to do a VLIST first so that there is 
sare tlata oo the screen. 
The four pararreters will need to be set, unless of 
course they have previously teen define:i, but for this eicarrple let us assurre that 
they haven't. 
To scroll a windc,,,,, at CDL 4, RCM 5 with height 4 characters and 
width 3 characters, with wrap, 4 pixels left, type the following: 


4 CX)L ! 5 RCM ! 4 (-J;T ! 3 IEN ! WRL4V <an 


If there is oo data on the screen, type: 


VLIST 4 COL ! 5 RCW ! 4 !t,T ! 3 LEN ! W:U:.4V <ffi> 


A. wind.CM collffl"l 4 Ro,,., 5 has been scrolled left 4 pixels - if you did• nt see it 
happen type, 
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WRL4V WRL4V WRL4V <CR> 


and you should see it! 


Pararreters do oot reset after the execution of the cxmna.nds, 
so to repeat the 
abJve, this time at oolurnn 10 and without wrap, you could use the following: 


10 CXlL ! OCL4V <CR> 


Vertical Scrolls 


These v.0rk in a similar way to the horizontal scrolls , blt in addition to setting 
up the windc.M with the four window pararreters OOL, R:::W, fG1' and LEN, a further 
variable NPX is used to give the size and direction of the scroll in pixels. A 
posi tive value for NPX causes upward scrolling and a negative value causes 
downward scrolling. 


Parameter 


CXlL 
RCM 
LEN 
ffiT 
NPX 


Ccmnand 


WCRV 
SCRV 


Note: 


Use 


Colurm at l eft hand edge of windCIW ( 0- 31) 
R°" of top l eft ooge of the window 10-23) 
Width of the wind.CM (1-32) 
Height of the windc,,,, (1-24) 
Nunber of pixels to scroll 1+127 to -128) 


Action 


Vertical scroll with wrap 
Vertical scroll, oo wrap 


All vertical scrolling of pixel data and/or attributes for screen or sprites, 
requires b.J.ffer space. 
The space required is calculated by multiplying NPX by 
LEN. 
The start of the b.lffer i s taken as the next free byte after sprite space, 
so be sure that either a <DLD# has been executed, or that SPNO has teen set. 
It 


is safe practice to develop sprites using the software provided, and to allow 256 
bytes b.iffer at the top before linking with the rrain program. 
Be sure also that 
the scroll length is oot greater than the window's size. 
On entry to White 
Lightning a WW# is autanatiacally executed and a scrolling blffer of 256 bytes 
is set ~. This is maintained s::, long as ISPRITE and CSPRITE are used in 
preference to SPRITE and WIPE. 


Attribute Scrolls 


Attribute scrolls are s imilar to the pixel data scrolls Wt all scroll s are always 
by ooe character, with wrap. 


Pararreter 
Use 


CXlL 
Colum of the left hand Erlge of the wiooc,,, I0-31 l 
RCM 
R°" of the top ooge of the window I 0-23 l 


lEN 
Width of the window (1-32) 


Im 
Height of the windc,,, 11-24 l 
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CCmnand 


ATTLV 
ATTRV 
ATTUPV 
ATTDNV 


Action 


Scroll attrib..ttes left 1 character with wrap 
Scroll attributes right 1 character with wrap 
Scroll attributes up 
1 character with wrap 
Scroll attributes down 
1 character with wrap 


SPRITE SCROLLS 


The format for these ccmnands is similar to that for the screen scrolls, except 
that these carmands are postfixed with an M as cpposed to a V. 


Horizontal Scrolls 


Parameters 


SPN 


Ccmnand 


WRL1M 
WRR1M 
SCL1M 
SCR1M 
WRL4M 
WRR4M 
SCL4M 
SCR4M 
WRL8M 
WRR8M 
SCL8M 
SCR8M 


Note: 


use 


The number of the sprite to be scrolled Cl to 2551 


Actions 


Scroll left l pixel with wrap 
Scroll right 1 pixel with wrap 
Scroll left 1 pixel, 
oo wrap 
Scroll right 1 pixel, 
no wrap 
Scroll left 4 pixels with wrap 
Scroll right 4 pixels with wrap 
Scroll left 4 pixels, 
no wrap 
Scroll right 4 pixels, 
no wrap 
Scroll left 8 pixels with wrap 
Scroll right 8 pixels with wrap 
Scroll left 8 pixels, 
no wrap 
Scroll right 8 pixels, 
oo wrap 


The chief purp:::,se of these cx:mnands is to give pixel resolution to the PUI' 
co:marrls, and for this reason, a l character lxlrder along 2 edges of a sprite 
character should always be allowed. 


Example: 


To scroll sprite number 7, 1 pixel right with wrap, use: 


7 SPN ! \.'RRlM 


Vertical Scrolls 


These WJrk in the sarre way as the vertical screen scrolls \obere the signed 
variable NPX is use:i to determine the size and direction of the scroll. 


Parameters 


SPN 
NPX 


Use 


Number of the sprite to ba scrolle:i 
Number of pixels to ba scrolled 
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Crnmand 


WCRM 
SCRM 


Exarrple: 


Action 


Vertical scroll with wrap 
Vertical scroll, 
oo wrap 


To scroll sprite 5 dCMnward by 11 pixels with wrap, use: 


5 SPN ! -11 NPX ! w:::RM 


Attribute Scrolls 


There are four cx:mnands to scroll attributes in any of the four directions: 


Pararreter 


SPN 


Crnmand 


ATTLM 
ATTRM 
ATTUPM 
ATTDNM 


Use 


Nu:nbe.r of the sprite to re scrolled 


Action 


Scroll attributes left with wrap 
Scroll attributes right with wrap 
Scroll attributes q;:> 
with wrap 


Scroll attributes de.Mn 
with wrap 


GETS AND PUTS 


There are three groups of GETs and Pl.11's. 
The first , and the fastest, carry out 
cperations between a full sprite and a previously defined windc:M of the screen. 
The second group carry out q>erations tetween sprite windows and screen windows. 
The third, and probably rrost ~rful group of o:mnands in the sub-language, cover 
cperations be~ sprite windows and other sprites. 


Sq;:,p:,se you have desiged a sprite 160 characters wide ( 5 screens) and you wish to 
srroothly pixel scroll through this sprite via a screen wind.CM covering the b::>ttan 
five character rc:MS of the screen. 
A second di.mmy sprite, 1 character wider t.han 


the screen can re used to GET fran the larger sprite, scroll, PUI', scroll, Put and 
so oo for 1 character, then a second block, 1 character further into the larger 
sprite can be oor and so oo. 
Experinentation will scxm show" you tx:,.,,.T to 00 this. 


These routines can be run in background to provide fast srooth scrolling 
backdrq;,s. 


Group1 


This group provides block rroves and logical q:,erations betweien sprites and screen 
windows - these are the fastest cx:mnands in the set. 
This particular group does 
not inclu:1.e seperate attribute cx::rmands b.lt instead uses an attribute switch. 
If 
the switch is oo, pixel data and attribute data are rroved; if you do oot require 
to nove attriOOtes you can increase the speed of cperations by switching off the 
attribute switch. 
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Camand 
Action 


ATTON 
Enable the flow of attribute data between the sprite and the screen 
wirrlow 


ATTOFF 
Disable the flOW" of attriOO.tes between the sprite and the screen 
window 


We row cnre to the group 1 ccmnands thensel ves: 


GETS 


Parameter 


SPN 
CXlL 
!01 


Camand 


GETBLS 
GETORS 
GETXRS 
GETNDS 


Note: 


Use 


Nunber of the sprite to be used (1 to 255) 
Left hand oolunu of target screen wind"" (0 to 31) 
Tep <™ of target screen wi~ (0 to 23) 


Action 


Block rrove screen window into sprite 
CR screen window into sprite 
XOR screen window' into sprite 
AND screen window into sprite 


The dimansions of the screen window are taken as the dirrensions of the sprite. If 
the cxmnand doesn't execute, it is alm:>st certainly because the width of the 
sprite+ CDL or the height of the sprite+ RO-J, exceed 32 or 24 respectively, so 
that part of the window lies off the screen. 
sprites must re previously set up 
either by the developernent software, or the CX>LD# and SPRITE or !SPRITE ccmnands 
before these o::mnands will execute. 


Exarrple: 


To GET a screen sprite into sprite number 4 £ran colum 5, rCM 4, with attributes 
and "CR" it with the data currently held in sprite number 4, use the follCMing: 


4 SPN ! 5 O)L ! 4 B0-1 ! ATION GE'IORS 


Note that if ATION was the last switch ccm:nan<l, it would oot be oeaied in the 
above. 


PUTS 


These c&mands are identical to the group 1 "Gb'"'TS" except that data transfer is 
fran the sprite to the screen. 
The results of the various cperations are 
therefore displayed. to the screen. 
The p:1.rarceters are identical in cperation to 


those of the "GETS", and the ATION and ATIOFF S'witch c:cmnands also apply. 


Pararreter 
Use 


SPN 
Number of the sprite to be used (1 to 255) 
OOL 
Left hand oolumn of target screen window ( 0 to 31) 


OC>W 
Tq:> rCM of target screen window CO to 23 l 
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COmland 


PUTBLS 
PUTORS 
PUTXRS 
PUTNDS 


Group 2 


Action 


Block rrove sprite window into screen 
CR sprite window into screen 
XOR sprite window into screen 
AND sprite window into scr-een 


These cxmrands allow operations between sprite windows and screen windows. 
Unlike 


Group 1 cacmands, there are separate o:rrmands to rrove pi xel data and at tributes, 
and the ATION, ATIOFF o:rrmands have oo effect on their cperation. 
'l\,,u re,,, 
pararreters are intro:luce:l to specify the CDLlMil and ROW of the top left hand 
character of the sprite window'. 
In 00.dition, lCl' and LEN are required. to specify 
the dimensions of the window for the screen and sprite. 


Paraneters 


CDL 
ROW 
9'.XJL 
SRCW 
IGl' 
LEN 
SPN 


Cannand 


GWBLS 
GWORS 
GWXRS 
GWNDS 
GWATTS 
PWBLS 
PWORS 
PWXRS 
PWNDS 
PWATTS 


Note: 


Use 


Left hand oolunn of target screen window CO to 31) 
Tep re,,, of target screen window ( 0 to 23) 
Left hand oolunn of target sprite window CO to sprite width -1) 
Tcp row- of target sprite window CO to sprite height -1) 
Height of window 
Length of window 
Sprite numter 


Action 


Get block of pixel data fran screen window into sprite window 
00. pixel data fran screen wind.ow into sprite window 
XOR pixel data fran screen windc:M into sprite window 
AND pixel data fran screen window into sprite window 
GE!' block of attrib.ite data fran screen windc,,,, into sprite window 
Pl11' block of pixel data fran screen window into sprite window 
CR pixel data fran sprite window into screen windc:1.,, 
XOR pixel data £ran sprite window into screen window 
AND pixel data fran sprite window into screen window 
Pl1l' block of attribute data fran sprite window into screen wi ndow 


If the cx:mrand cbes oot execute, check that the windorw' is oot P3rtially off the 
screen or sprite. 


Exa!rple : 


To block rrove a window 3 characters high and 4 characters wide fran ITM 2, ool mn 
3 of the screen to row 4, oolunn 6 of spr ite nun.her 7, use the follc,,,,ing: 


7SPN I 3 !m I 4IBN ! 210< ! 3CDL ! 4 SIOI ! 69'.XJL I GiBrS 


Note that sprite 7 must be at least 8 characters wide and 7 characters hi gh for 
the o:mnand to execute. 
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Group3 


This group, p:,ssibly the nest useful in the whole set, cx:nprises cx:mnands which 
support cperations between sprites and sprite windc7ws. 
The sarre set of cx:rrmands 
as those in Group 2 are available and the foanat for each word is the sarre as in 
Group 2, except that the ccmnands are postfixed with an "M" instead of an "S". 
The chief difference to the user lies in the set of parameters. 
The size of the 
data window is set to have the di.Irensions of the first sprite, and its position in 
the second sprite is set using the 9:X>L and 9tCM pa.rarreters. 


Pararreter 


SPl 
SP2 
OCOL 
SRCW 


Catmand 


GWBLM 
GWORM 
GWXRM 
GWNDM 
GWATTM 


PWBLM 
PWORM 
PWXRM 
PWNDM 
PWATTM 


Note: 


Use 


Ntlllber of the first sprite 
Nl.lrlber of the second sprite (containing the wind.OW") 
Left hand oolunn of target sprite windOW' 
Tep re,.,, of target sprite window 


Ac..tion 


Block rrove pixel data fron first sprite into windOW" in second sprite 
OR pixel data fran first sprite into window in second sprite 
XOR pixel data £ran first sprite into window in second sprite 
AND pixel data fran first sprite into windc:M in second sprite 
Blcx::k rrove attribute data fran first sprite into window in second 
sprite 
Block rrove pixel data fran windCM' in second sprite into first sprite 
00. pixel data fran window in second sprite into first sprite 
XOR pixel data £ran window in second sprite into first spri te 
AND pixel data £ran window in second sprite into first sprite 
Block nove attribute data £ran window in second sprite into first 
sprite 


If the width of the first sprite a:iderl to 9:X>L, or the height of the first sprite 
adde:l to SRCW exc:eeds either the width or height of the second sprite 
respecti ve1 y, then the ccmrand will not execute. 


COPY COMMANDS 


These five cxmnands , are in fact a sub-group of the Group 3 ccmnands and allow 
cperations between pairs of sprites with the same dimensions. It is necessary, 
therefore, to provide ooly tw:J pa.rarreters instead of four. 


Pararreter 


SPl 
SP2 


Use 


Number of first sprite 
Nl.lllber of second sprite 
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Canrand 


COPYM 
COPORM 
COPXRM 
COPNDM 
COPATTM 


~ate: 


Action 


Cq,y first sprite pixel data into second sprite 
OR first sprite pixel data into second sprite 
XOR first sprite pixel data into second sprite 
AND first sprite pixel data into second sprite 
Cq;>y first sprite attribute data into second sprite 


If the di..rrensir-:1s of the ~ 
sprites are not identical, then the crnmand will not 
execute. 


Exarrple: 


To rrake a a::rrplete ccpy of sprite 10 into sprite 8, use the folla,,,ing: 


8 SPl ! 10 SP2 ! CXlPl'.M Cl'.lPATlM 


SPRITE TRANSFORMATIONS 


To increase the utility of the pa.ckage, four extra \loOrds have teen added. to 
i nvert, spin, reflect and enlarge sprites. 
The inversion and reflection routines 
~rk for ;creen and sprite data b..lt the rotation and enlargerent ccmnands \loOrk 
on 1.y on sprites and a dumny sprite is required to rotate or enlarge into. 


Inversions 


The sprite is "l's cx:rrplerented"; in other w:irds , all the pixels which are set 
"on", becane set "off" and vice-versa. 
The attributes, ~ver, ranain 
i.mchangerl. 


Pararrete:r 


SPN 


Cam'and 


INVM 


Pararreter 


Use 


The number of the sprite to be inverted 


Action 


The sprite is inverted (1 1 s cx:nplemented) 


Use 


CDL 
Colurm of the lei _ hand edge of the screen windCM CO to 31) 


IOI 
R"" of the top erlge of the window ( 0 to 23 ) 
LEN 
Width of the screen window (1 to 32 ) 
J;J;T 
Height of the screen window ( 1 to 24 l 


Canrand 


INVV 
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Action 


Invert screen window 


Reflections 


There are four oo:itnands in this group for reflecting screen and rreoory, pixel and 
attrib.lte data. 
A sprite is often required to p::,int in ~ 
directions and the 
carrrand can either be used at the developrent stage or, if space is short, at 
run-tine. 
The a:mnand causes h:>rizontal reflection blt vertical reflection is 
possible, by cx:mbining rotations and reflections. 


Paraneter 


SPN 


Ccmrand 


MIRM 
MARM 


Paraneter 


Use 


Nanber of sprite to be reflecte:i Cl to 255) 


Action 


Reflect sprite pixel data about its oentre 
Reflect sprite attrib.lte data about its centre 


Use 


CDL 
Column of left hand Edge of screen windc,..,, ( 0 to 31) 
RCM 
RCM of top a'lge of the wind"" CO to 23) 
LEN 
Width of screen windCM Cl to 32 l 
ICr 
Height of screen windCM Cl to 24) 


Ccmrand 


MIRV 
MARV 


Spin 


Action 


Reflect screen pixel data about wind.CM centre 
Reflect screen attrib..Ite data about windc,..,, centre 


This o::rmand involves an q;,eration bet~ ~ 
sprites with transEX)se:i dbrensions. 
If, for exarrple, a sprite with di.rrensions 8 by 3 is to be spun into a second 
sprite, this second sprite JlUJSt have di.rrensions 3 by 8. 
Square sprites are, of 


course, no problem. 
Pixel and attribute data ar.e l:oth rotated. If the carmand is 
to be used, it is :inp:>rtant to remember that a second sprite will be needed to be 
rotated into and that i t is necessary to set this up in advance. 
Rotation is 90 


degrees clockwise. 


Parameter 
Use 


SP2 
Ntrnber of sprite to be rotated 
SPl 
Number of sprite to be rotated into 


Camand 
Action 


SPINM 
Rotate 90 degrees clockwise sprite SP2 into sprite SPL 


Note: 


A sprite cannot be rotated into itself, i.e. if SPl and SP2 are the same number, 
the rotation will not work. 
The result is, however, well tt.0rth seeing! 
Data is 
"CR"ei fran SP2 i nto SPl so it is usually necessary to execute a Cl.SM to clear 
sprite SPl before execution. 
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Enlargement 


One a:mnand is provided for enlarging a sprite and its attributes into a second 
sprite ~ich has dirrensions exactly double those of the sprite l:eing enlarged. 


Pararreter 


SPl 


SP2 


Canrand 


DSPM 


Note: 


Use 


Nunl:::er of the sprite into ~ich the enlargenemt is carried 
out. 
Number of the sprite l:eing enlarged. 


Action 


Enlarge sprite SP2 into sprite SPL 


If the dinensions of sprite SPl are not twice those of sprite SP2 the camand will 
not execute. 


INTERRUPT RELATED WORDS 


Six interrupt related \ooOrds are provide:3 ~ich control the Foreground/Background 
execution of White Lightning ~rds. 
The first four have no pararreters. 


Canrand 


HALT 


El 


DI 


EXX 


INT-ON 


INT-OFF 


Exanple: 


Action 


Suspend CPU cperation until the next interrupt. 
Executing 


HALT in background rrode will freeze the system permanently. 


Enable the interrupt. 


Disable the interrupt. 


Exchange IDFAL variables with the alternate IDFAL variables. 
This cx:mnand is execute:i autanatically each tine an 
interrupt o:curs and at the end of the interrupt routine 
to restore foreground variables. 
If a backgrourrl program 


is oot teing used FXX can l:e used to provide extra variables. 


The specifie:3 ~rd (see next exanple) is executed oo the 
receipt of each interrupt. 


FollCMing execution of ~FF the ZS0 returns to interrupt 
rro:ie 1 and polls the keyboard 50 times a =nil. 
The 
background program oeases execution. 


To set a lliOrd running in background type: 


I w:R[) JNT-0,J 


Where "K>RD" is the \,,Ord to te run in background. 
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BASIC INTERFACE WOROS 


These w:>rds are provided to enable you to mix BASIC and Forth in :your program. 
The section oovering the access of BASIC should be read carefully l:efore an 
atterrpt is rrade to use these ccrmands. 


Camand 


PROG 


RESERVE 


Exanple: 


1024 RESERVE 


Action 


Enter BASIC at a:mnand level. 


Reserve space in the dictionary for the insertion of BASIC 
source. 
The size of the space to be reserved is taken fran 
the stack. 


will reserve 1k. £ran the current value of HERE. 


GOTO 
The BA.SIC program is executed £ran the line numter held 
on the stack. 
Forth can l:e called £ran Bl\SIC using 
RANI:01ISE tER 30000 and Forth can te re-entered using 
PRINI' lER 30006. 


Exanple: 


100= 


will cx:nnence execution of the Bi\SIC source £ran line 100. 


RETUSR 
Cootrol is returmrl to the PASIC program £ran Forth. 
Execution of the BASIC program proceeds with the first 
instruction after the RANIXMISE lSR 30000 with which Forth 
was called. 
D:J oot execute a RETUSR in Forth if Forth has 
not been called using a RANOCMISE lER 30000 call. 


MISCELLANEOUS WORDS 


There are 18 \toOrds provided which cover general aspects of garres developnent. 


Ccmnand 


SETAV 


SETAM 


CLSV 


CLSM 


Action 


set the attributes t.o the current INK and PAPER oolours in 
the screen window defined by lCI', LEN, O)L, .RJ'>J. 


Set the attributes to the current INK and PAPER oolours in 
the sprite whose number is held in SPN. 


Clear the screen window (defined by fliT , IBN, CX)L, IO-J) 
of pixel data and set the attributes throughout to the 
current INK and PAPER oolours. 


Clear the pixel data of the sprite whose number is held 
in SPN. 
Attribute data is unaffected. 
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ADJM 
This ccmnand is used to ensure the execution of group2 GET 
and PUl' instructions. 
The pararret.ers are SPN, Cl)L and RCW. 
First JC1' and IEN are set to the dimensions of the sprite 
whose number' is held in SPN. 
If O)L or R:::M are "off 
screen" or if OOL + IEN, Em + RCW are off screen, then 


Exanple: 


the pararret.ers CDL, RCM, H3T, LEN, S:OL, SRCM are set such 
that the sprite will 00 partially PUI' to the screen or 
001' fran the screen. 
This is an extremely useful cx:mnand 
and can be used in conjunction with any of the group 2 GETs 
and Pills. 


-1 Cl)L ! -1 RGl" ! l SPN ! AllJM PWBIS 


This will PUT part of sprite 1 in the top left hand oorner. 
After execution, Cl)L 
and 0CM will have l:een rrade O and S::OL and ~ 
will have the value 1. 


ADJV 


SCANM 


SCANV 


RND 


Example: 


10 RND 


Essentially the same: idea as AD.JM rut this tine the screen 
wind.CM defined by IC!', IEN, OOL, RCM is crljusted to lie 
"on screen". 


The sprite whose number is held in SPN is scanned for 
pixel data. 
If data is found a true (oon-zero> flag is 
placed on the stack, otherwise a false (zero> flag is 
placed on the stack. 
This CXJT11W1d is used extensively for 
collision detection. 


The dlarat.er cell at screen positions defined. by OOL arrl 
RCM is scanned. for screen data and a true or false flag 
stacked accordingly. 
This a::mnand executes rrore rapidly 


than OCANM. 


Replace the value at the top of the stack by a randan 
number t::etween zero and the value at the top of the stack. 


will leave a number t::etween 0 and 10 oo the stack. 


OUT :tt 
Output the second value on the stack to the port crldress 
at the top of the stack. 


IN" 
Replace the port ,rldress oo the top of the stack by the 
16 bit representation of the 8 bit numl:er read fran the 
port. 


Exanple: 


The following will poll the Kanpston Joystick and execute ooe of 8 ..,rds depending 
en the joystick position. 
Finally, the fire b.ltton will be tested. Type: 
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: JOYSTICK 31 INI IlUP CASE <ra> 
0 OF ." c»nRE," ENOOF <CR> 
l OF • " RIGHT " ENOOF ~CR> 
2 OF • " I.EFT " ENOOF ~> 
4 OF • " JDiN " ENIDF <ii,11.> 
8 OF • " UP " ENOOF <ffi)' 
9 OF • " lPRIGHT " ENIDF <CR> 
10 OF • " tFLEFI' 11 ENOOF <rn> 
5 OF • 11 o::MNRIGHT " ENOOF <CR> 
6 OF • 11 ~ 
" ENOOF <CR> 
ENOCASE <CR> 
15 > IF • " FIRE " ENOIF ; <rn.> 
: JTEST IE,IN JOYSTICK CR 1 1 KB !NrIL ; <CR> 


To run type: 


J"IBST<CR> 


To ha.It press CAPS SHIFT 


KB 
This cx:mnand is provided for the detection of multiple key 
presses. 
All it does, in fact, is test the specified key 
and stack a true flag if the key is pressed and a false flag if 
it is oot. 
The key to t:e t.ested is specified by the top 0-.U 
numbers oo the stack. 
The second value specifies the half IOI 
and the top value the CDLlMN. 
For a full description 
of the (l)LU!NS and IOIS of the Spectrum keyboard see page 160 
of the Spectrum manual. 
Below- is a surmary. 


IOI 
KEl'S 


CAPS SIIIFr to V 
A to G 
Q to T 
1 to 5 
0 to 6 
P to 7 
ENl'ERtoH 
SPACE to B 


Colurms are organised fran 1 to 5 and oounte:J. fran the outside in. 
This is the 
order al:x>ve. 


BLEEP 


Exanple: 


This c:perates in the sarre way as the Spectrum' s BEEP 
carmand with the second number oo the stack providing 
duration and top numbe.r pitch. 


100 200 BLEEP 


ATTON 
After the execution of ATION, group 1 GETs and PUTs will GET 
and PUT attribute data at the sa.ne tine as they GET and Ptrr 
pixel data. 
The G4 and ~ cxmnands, however, are unaffected 
by ATION or ATIOFF and always use separate cx:mna.nds to 
rrove pixel data. 
After the execution of a G,'l or R-v cx:mnand 
the attribute switch is always set to 'OFF'. 
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ATTOFF 


CALL 


Exanple: 


After the execution of ATroFF, group GETs and PtJI's will rrove 
pixel data only. 


Control jurps to a machine cx:>de subroutine whose a:ldress 
is held at the top of the stack. 


HEX 0000 CALL 


~uld execute a machine o::rle subroutine at location 0000 HEX. Cbn' t type this 
unless you have a machi ne code routine at' HEX 0000 ! 


ZAP 


ZAPINT 


PAT-ON 


PAT-OFF 


Exanple: 


Once program develop:nent is a::mplet el and you have canpiled 
your f inal program into the dictionary, typing ZAP will 
prcxluce a run-time vers ion. 
The le ngth of the final 
version is displayed to the screen and a copy can l:e save:l 
by typing: 


SA.VE "file narre" CX)DE 24832 , I...EN::;TH 


the length l:eing the length displayed.. 
Typing: 


PRINT l£R 24832 


will execute the last ~rd defined refor e the ZAP ccmnand. 
This is the only fonn in which White Lightning programs 
can be camercially sold. 


As alx>ve except that programs \oktich utilise the 
For09"round./Backgrourxl facility must be prOO.uced using the 
ZAPINT =nnand as cpposa:l to the ZAP o:nmand. 
The only 


real difference is that the first five screens also need 
to be saverl and that the top 16 bytes of RI\M will be 
used by the final pro:::Jram. 


All subsequent screen output is to ZX-Printer only. 


All subsequent output is to screen only. 


PRT---ON VLIST PRT-OFF 


will lis t the rur rent FORTH dictionary to the ZX-Printer. 
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FORTH/ BASIC WORDS 


For those users who have rrastered and grown used to the Spectrum I s own graphics 
camands, a set of 18 Forth i.rrq;:>lementations of Spectrum words is provided. 
Parameters are place:l en the stack in the sarre order as they occur in their PASIC 
inplanentations. If an error occurs during the execution of a eASIC word, Forth 
should be re-entered via a WARM start, i. e. PRINT l.SR 24836. 
For a full 


description of the action of each of these \triOrds refer to your Spectrum manual. 


R::w, (l)L 


OJI.OUR 


X, Y, AN:;IB 


X,Y,RADilS 


X, Y 


X, Y 


IOl,OJL 


IOI, a)L 


X,Y 


a)L 


a)I.DUR 


a)!.DUR 


FLAG 


FLAG 


FLAG 


l\CTION 


COPY 
The screen in 'durrped I to the ZX-Printer. 


AT 
The print p::,sition is rroved the specified 
COlunn and Ro,. 


BORDER 
The l:order colour is set to ooe of the 8 
Spectrum colours. 


CLS 
The screen is cleare:1 of pixel data and the 
attrib..ttes set to the current INK, PAPER, 
ERIGHT and FIASH values. 


DRAW-ARC See Spectrum nanual page 122. 


CIRCLE 
See Spectrum nanual page 123. 


DRAW 
See Spectrum nanual page 121. 


PLOT 
See Spectrum nanual page 121. 


SCREEN$ 
The character at the screen I,X>Sition defined 
by the two values at the top of the stack is 
tested to see if it is ooe of the Spectrum' s 
pre-defined dlaracters. 
The AS::II value 
is left on the stack. 


ATTR 
The cx:xle for the attdbJt.e at the screen 
p::>si tion defined bf the top bro values on the 
stack is left on the stack. 


POINT 
The pixel at the Cx,y) c:o-ord defined by the 
top b«l values on the stack is tested and 


TAB 


INK 


PAPER 


a true or false flag stacked. depend.ing oo 
whether the pixel is set or oot. 


Set the OOrizontal print J;X)sition to the 
value at the top of the stack. 


Set the INK col our to the value at the top 
of the stack. 


Set the PAPER colour to the value at the top 
of the stack. 


OVER. 
Note the full stop at the end of OVER. 
This sets the printing m:xle according to 
the value of FLAG which is zero or one. 


INVERSE 
As for OvER. 


BRIGHT 
As for OVER. 
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FOREGROUND BACKGROUND 


Mastering rrachine oode does give nost prograrrmers access to the speerl of 
cx:mrercial garres, rut often the sroothness and oontinuity are lacking. 
One of the 
greatest difficulties facing any garres designer is timing. 
The basic problan is 
that sane parts of the program nee::l to execute at regular intervals, and trying to 
achieve this can involve a lot of calculation and wasted processor tine. 
The 


solution to this is to use interrupts to execute particular sections of o::rle. 
White Lightning does this for you, using the v.0rds INT--ON and INT--OFF. 


The Spectrum interrupt occurs 50 times a second, so background v.0rds can l:e 
executed at this freq1Ency, or ~ oounting interrupts, at lower frequencies. 


If you list any of the screens 1 to 5, you will see that they are apparently 
filled with garbage. 
This is l:ecause the area in rrenory occupie:1 by these screens 


contains the rrachine oode that enables the background facility. 
If you are not 


intending to use this facility, then you can clear screens 1 to 5 and use than 
nonnally for source code. If you do this, however, don't forget that you "A'On't be 
able to use any of the graphics ~rds in background. node, or the system will crash 
in oo 1.mcertain rranner ! 


When an interrupt occurs, the foreg-round prcqram stops exactly where it is, saves 
off its paraneters and then executes the background \roQrd. 
The background \roOrd 
will then execute fully before continuing execution of the foreground pro:Jram, 
fran the exact fX)int at which it was halted. 
Three important i;x:,ints should be 
bourne in mind. 
Firstly, if the execution t.i..re of the background "A'Ord excee::1s a 
fiftieth of a second, it is not fX)Ssible to execute it rrore than twenty five tines 
a second, if it exceeds a twE!nty-fifth of a second, it can ooly te executed at 
half that frequency, and so oo. 
There is, h:Jwever, no limit to the length of the 
backgrowxi execution time itself. 
Secondly, as the execution tine approaches a 


fiftieth of a second, or sare multiple of a fiftieth of a second, then less and 
less prcx:essor time will te available for the foreground prcqram and s::metimes it 
is necessary to extend the length of the background. program to make the foregrourrl 
program run nore quickly, by reducing the frequency of the background program. 
Experiirentation will familiarise the user with the techniques required for the 
best effects. 
More foreground time can also be taken l:>j disabling and then 


re-enabling the interrupt using DI and EI respectively. 
This brings us to the 
third, and nost inportant p:,int. 
Ranember that when an interrupt cccurs, the 
foreground prcgram will stop whatever it is OOing, execute the b:tckground program 
and then o:mtinue with the foreground. execution. 
Supp:::,se the background program 


is a side;,,a.ys scroll of a user defined screen windc:M and the foreground program 
Ptrrs a dlaracter into the window. 
A problan arises if an interrupt occurs halfway 
through the rur, because the top half of the character will be scrolled before the 
second half of the character is PUT to the screen. 
To circumvent this problen, 
where an cperation is carried out oo the sane screen or sprite data cy' toth the 
foreground and background programs, the background. program should te tenp:>rarily 
disabled using DI, the foreground. \toOrd executed, and then the background program 
re-enabled using EI ready for the next interrupt to occur. 
The safest way to 
prcceed until you have really mastered the language, is to avoid the situation 
altog"ether and make sure the foreground and background programs don't q,erate oo. 
the sarre sprite or screen area. 


To set the background program running, si.JTply type an apostrophe Cshifte:1 7), a 
space, the w::>rd to be execute:1, a space and then INIY)N. 
Dcx1 1 t forget that if the 
background word ooes not set its own paraneters, then these will need to be set 
b:!fore execution and if these are the IDFAL variables, then the alternate set will 
be used. 


67 


Fer exanple, suppose you letltai to scroll a windc:M, four characters square, in the 
middle of the screen and invert it after each sideways scroll. First we need to 
define a \IIOrd to 00, the scrolling and the inverting. 
For sare reason, rcost test 


programs are called FRED and there is oo reason for breaking with oonvention. 
To 


define the ""'rd type: 


1 FRED ~lV IlNV ; <Cl!> 


To set up the parameters type: 


4 fm ' I 4 IEN' I 14 OOL' ! 9 R:M'' ! <CR> 


To nake sure there is sane data in the wiOOCM, type: 


VLIST <Cl!> 


Yoo are ~ 
ready to execute the background program by typing: 


I FRED INI'-00 <CR> 


To halt this program type: 


ml'-oFF <Cll> 


This program is rwming a bit too fast to see, so let's write another program 
tiihich slows this down to every fifth int.errupt, i. e. ten tines a second. 
We will 


need to define a variable and a new 't.Ord. 
To set up the variable type: 


0 Vl\RIAl!IB = <Cl!> 


This sets up a variable called JCNT and assigns to it the value O. 
We' 11 call 


this new background ""'rd FRED!\. 
Type: 


: FREDA. !Cm' @ l+ 5 > IF FRF.O O JCNT ! ELSE l ICNT +! ENOIF ; <rn> 


New type: 


I FREDA. INT-00 <CR> 


All "FREDA." does, is to incranent ICNT and o:::rrpare it with 5 and if it is greater 
than 5 then "FREDA." is execute3. and ICN1' set back to -zero. 


' 
It ""°uld be useful to be able to cxmtrol the speErl that 
"FREDA." ran at, so, let's 


m:x:lify "FREM" to do this. First, type INT-OFF FORGET FREDA <CR> to get rid of 
the old definition and then set '-l' a new variable and oonstruct a slightly 
different program. 
A variable \itlich sets the limit on the number of interrupts 


needs to be set up, so type: 4 VARIABLE ICNI' <rn>. 
The new definition is set lt> 


by typigg: 
. 


: FRED!\ ICNr @ l+ ICNT @ > IF FRED O ICNT ! EISE 1 ICNT +! ENDIF ; <Cl!> 


To execute the new ""°rd type: 


o ICNI' 1 ' FREDA. INT-oo <rn> 


This program incranents ICNI', cx:mpares it with ICNI' and executes when ICNT is 
equal to ICNl'. 
Increasing U::Nl' then, will sl°"" the background execution and 


decrE!l'W:mting tcNT will speed it up. 
If lCNT is put equal to 1, execution will 


0C..'C1Jr el/ery cycle. 
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To speed. up "FREDA." type: 0 ICNT ! 2 I.Cm" ! <CR> and to slow "FREDA." type 10 ICNT 
! <Cll> and so oo. 
Type: INT--OFF <Cll> to halt FREDA.. 
Now type: roRGET FREDA. <Cll> 


Frequency and PhaH 


One of the problens with executing a word on each interrupt, 
is that the dot 
scanning the screen nay overtake the screen q:ieration in the sarre p:,sition on each 
execution. 
This can prcduce ocrre strange effects, and often, sections of the 
screen window will appear to l:e "sliced" . It is rrore usual to execute oo selected 
interrupts. 
We can do this very sinply using m:rlular aritmetic. 


Sq:,pose we have four different words that we wish to execute with four different 
frequencies. 
S~p:,se they are as follCMS: 


IllW 
MIRV 
WRRlV 
IO<V 


every 50 cycles 
every 20 cycles 
every 
4 cycles 
every 
5 cycles 


We now define a variable to oount interrupts and four oonstants to store the 
frequencies. 


0 Vl\RIABLE ICITT 50 CXlNSTANr Fl 20 OJNSTANT F2 4 OJNSTANT F3 5 OJNSTANT F4 <Cll> 
: MN) M)D ABS 0= ; <Cll> 
: !RUN ICNr @ 00P 00P 00P <Cll> 
Fl MN) IF IllW ENDIF <Cll> 
F2 Mro IF MIRV ENDIF <Cll> 
F3 MN) IF ~!UV ENDIF <Cll> 
F4 MN) IF l'CRV ENDIF <Cll> 
lICITT@+l;<Cll> 


All we need to 00 now is set Lt) the pararreters by typing: 


10 OOL' ! 10 ~• ! 6 1-Gl'' ! 8 LEN' ! 2 NPX 1 1 <CR> 


then p.1t sare data oo to the screen and execute: 


VLIST 0 0 NI! ' !RUN INT--ON <Cll> 


To tenninate, type INT-QFF <CR> 


If we had made the Fl to F4 variables, we oould have oontrolle:3 the tackground 
program fran the fore:Jrouncl by resetting than. 


SCin2tirres, oontrolling the frequencies of events is oot sufficient and phase 
information needs to be intrcrluced. 
In the previous exarcple, values of O, 100, 


200, 300 and so oo cause all four events. 
Sl{)POSing we \6Ilted to naintain these 


frequencies, tut change the order in \otlich the i.«>rds execute - we nee:i to 
intro:luce the concept of phase. 


In this exanple we need four rrore constants, so type: 


roRGEI' IRON <Cll> 


31 CXlNSTANr PIil 5 CXNSTANT PH2 0 CXlNSTANr PH3 3 CXlNSTANr PH4 <Cll> 
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- 
type: 


: m UN ICNl' @ 00P 00P 00P <CR> 
Fl MJD ABS PIil = IF "INI/V ENOIF <CR> 
F2 MJD ABS 1'112 = IF MIRV ENDIF <CR> 
F3 MJD ABS 1'113 = IF WRRl'l ENDIF <CR> 
F4 MJD ABS 1'114 = IF ICR'l ENDIF <CR> 
1 ICNl' + ! ; <CR> 


This can be: executed using VLIST 
I IRUN INl'--00 <CR> 


Halted using: INI'-OFF <Cll> 
and cleare:l using: FORGET mUN <CR> 


Forth/ BASIC Words 


Sinclair's graphics and sound ccmnands have teen replicated as Forth w:>rds for 
cont i nuity - they also execute slightly nore rapidly than their BASIC 
counterparts. 
For a full list, see the section oo Forth/BASIC W:JRil3. 


They all execute o:xle in Sinclair' s CM11 RCM ¼hich, unlike Forth aoo. IDFAL, is oot 
re-entrant. 
This rreans that these w:>rds cannot te executed in foregrourrl and 


background simultaneously. 
The FOR'lli words . " , • and U. should also not be 


executed simultanteously with thenselves or any of the BASIC ltoOrds. 
None of the 


Forth/BASIC w:>rds, 
" , • or U. should be executed in backgrourrl Wile Forth is in 


cannand node. 
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LOGICAL OPERATIONS 


There are three types of logical cperation inclu:ied in the IDEAL sub-language; 
these are CR, XOR arp AND. 
To get the test out of this package it is irrportant to 


make full USE:! of these o::rcrrands. 


If a GET or PlJI' (X)Stfixed. with "BIS" or "BIM" is executed, 
then data is block 


rroved fran the source which may l:e part of the screen, a sprite, or a sprite 
window, in such a way that whatever was previously held at the destination which 
may also be part of the screen, a sprite, or a sprite window, is OOliterated and 
replaced by whatever was at the source. 
This may not always be the desired effect 
and quite often the user will want to rrerge characters or rerrove parts of the 
characters and so on. 


If two sprites are "CR"erl together, the resulting sprite will have pixels set 
where pixels ~re set in either or l:oth of the sprites being "CR"ed. 


If two sprites are "AND"ei together, the resulting sprite will have pixels set 
where pixels ~re set in 00th of the sprites teing "AND"a:L 


If two sprites are "XOR"e::l together, the resulting sprite will have pixels set 
where pixels were set in either tut reset where pixels were set or reset in b:>th. 


These results are surrmarised as follCMS and should make things a little clearer: 


SOURCE 
OESTINATION 
OPERATION 
RESULT 


on 
on 
CR 
on 
on 
off 
OR 
on 
off 
on 
CR 
on 


off 
off 
CR 
off 


on 
on 
l\ND 
on 
on 
off 
ANO 
off 


off 
on 
l\ND 
off 


off 
off 
l\NO 
off 


on 
00 
IDR 
off 


on 
off 
l([)R 
on 
off 
on 
XOR 
00 
off 
off 
l([)R 
o~f 


We can 110W' use the sanple sprites to illustrate the effects of these operations. 
First FORGET any previously defined words and type: IE:IMAL <rn> to ensure that 
you are in decimal rrode. NCM type: 


7 INK O PAPER CLS • " ra.;rCAL CR " rn • " ra.;rCAL CR " <CR> 


This will clear the screen and µit sare data in the top left hand oorner. 


Na, type: 


3 SPN ! 0 (X)L ! 0 RCM ! ATIDFF PU'lORS <CR> 


Yoo will see that the data has been merged together, both the dragster and the 
letters remain. 


71 


Now type: 


CLS • n I.CX;ICAL AND " CR • 11 I!XiICAL AND 
II PUlNOO <CR> 


This time, the ooly data remaining is at those points where the data ooincided. 
Lcgical "AND"s are oonrally usei to nark off sections of the screen or sprites. 
They are also use:i extensively for oollision detection. If a window of the screen 
is "AND"Ed into a sprite, and then a s::::MN performed, it is possible to detennine 
whether a collision \i.Ould OC'CUr if the sprite were PU!'; before actually PUI'ting 
the sprite. 


We now cx:me to the logical IDR. 
This is probably the m:>st useful operation of the 


lot. "XOR "s have the peculiar prq:,erty of restoring the destination data to its 
fomer state if the c:peration is performed twice. 
This is h:::M Sinclair 1 s °""1 


"OJER" operatipn \IQrks. 
To see this happen type: 


CLS • " XOR " al • " }Q)R. " PurxRS <CR> 


To restore the text type: 


PUTXRS <CR> 


We can even use this prq;:,erty to swap t:wo sprites without using a third. 
This 
exanple will swap the data b.lt oot the attributes. 
We will "PU!'" two sprites at 


each stage so you can see what is happening. 
Type: 


CLS ATION O g;()L ! 0 SRO; ! l SPl ! 2 SP2 ! 23 CDL ! 6 0 M <CR> 


Now type: 


l SPN ! PUTBIS 2 SPN ! 27 CDL I PUTBIS <CR> 


These are the t:wo sprites bafore the (t)erations begin. 
Nool' type: 


QiXRM 2 RCM ! 23 (X)L ! 1 SPN ! PTJI'BIS 27 OOL ! 2 SPN ! PUl'BLS <Cl\> 


sprite 1 has OCM been "XDR"e:l into sprite 2. 
NCM type: 


iWI'XRM. 4 row ! 23 (l)L ! 1 SPN ! Pl1l'BlS 27 (l)L ! 2 SPN ! PlTI'BIS <CR> 


sprite 2 is raw in sprite 1. 
Finally, type: 


QiXRM 6 IOI ! 23 CDL ! l SPN 
PUTBIS 27 (X)L 
2 SPN 
PUTBIS <CR> 


The q>eration is OCYw cx:JT{)lete. 


If we wanted to aid a ne-w word to the language which swaps two equally sized 
sprites whose numbers were in SP1 and SP2, we would now do so. 


: !HJP O s:lJL ! 0 SIOI ! G-IXRM l'WXRM Q;XRM ; <CR> 


In fact we could also use: 


: SW)t> 0 SX>L ! 0 ~ 
! PWXRM Gr\'XRM PWXRM ; <CR> 


for exactly the same effect. 
You will get MSG # 4 if you type the second word 


before typing FORGET S'l:lP <CR> 


Ironically, even though we can swap pixel data, there is no sinple rrethcxl for 
swapping attribute data unless a third sprite is involverl. 
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COLLISION DETECTION AND SPRITE RECOGNITION 


T\ttO words are provided for collision detection, these are s:::ANV and s::At-11. 


OCANV is use::i to scan a particular character p:,si tion on the screen. 
If any data 
is present in the specified. square (oo-ords are held in (l)L and RCM), then a true 
flag is place::l on the stack and if the square is anpty (contains oo pixel data), a 
false flag is placed on the stack. 
Type: 


OS VLIST O Vl\RIABLE CNr <CR> 


This will put scrre data on the screen and initiate the variable OIT. 
NcM type: 


: 00 0 ml' ! 24 0 00 I RCM ! 32 0 <CR> 
00 I O)L ! &:ANY IF l Off +! <at> 
FNDIF IOOP IOOP CNI' ? ; <Cl<> 


This defines a word which simply counts the number of characters oo the screen. 
Type: 


00 <CR> 


This should print a number sarewhere around 250. 


Often it is insufficient to determine whether a particular character square 
contains data or oot, and for this reason the slower, bJt rrore powerful ccmnand 
OCAtfl., has l::een inclu:led. This will scan the sprite whose number is held in SPN 
and put a true flag oo the stack if the sprite oontains pixel data, or a false 
flag if it does oot. 
s::Al'N is oonnally userl to perform one of three functions: 


l. 
To see if data will CX>llide. 


2. 
To detect an exact pattern. 


3. 
To detect the presence of a pattern. 


Collision detection is nest cnmonly usErl. to detect a collision between a sprite 
roving across the screen and any data which lies in its path. 
Often the sprite 
can pass through an occupied character (X)Sition without a collision occurring, so 
the ~ 
ccnmand is insufficient. 
The procedure is basically to load a dumny 
sprite with the section of screen into which the sprite is about to te PUI', "AND" 
it with the sprite about to be PUl' and then use s:::At-1-1. 
If a true flag is co the 
stack the durrmy sprite oontains data and therefore a oollision has occurred. 
This 


is all very well, bJ.t a problem occurs if the new sprite position overlaps the old 
sprite (X)sition, because this rreans that the old sprite has to te renoved frcrn the 
screen before beginning the above detection procedure and subsequently PlJl'ting the 
new sprite. 
This delay causes flicker. 
The easiest solution is to "-Ork with 
"IDR"s so that the windc,,,, can be ror, "XOR"e:l with the old sprite in rrerory to 
rarove the old sprite data, and then to 00 the detection follc,.,al finally by the 
blotting and then inmadiate PUTting. 


Once an inpending oollision is detecte:i it is frequently useful to determine what 
the sprite has collided with. 
To begin with, let's assurre that the screen window 
we' re examining oontains coe of a known set of OOjects and that no other data is 
present in the window. 
The m,thod is to load the durrmy sprite with the object to 
be tested and then carpare it ~ainst the set of sprites with which a rratch is 
being sought. 
To carpare the dumny sprite with a known sprite, all you need to do 
is XOR the sprite being tested into the durrmy and 00 a OCAN-1. 
If the result is 
zero, an exact natch leS fmmd, if not, do a second XOR into the dumny t.o restore 
it and test the next candidate. 
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Finally, consider the case where the object being tested contains extraneous data 
in a:l.dition to one of the possible sprites. 
This tine, the dumny sprite is 


loade:i with the contents of the screen window, blt the candidates are first 
"AND"ed into the dumny to rerrove extraneous data before the XOR and ~- 
Finally the dumny nee:is to l:e reloaded fran the screen before the next test. 
This 


latter test is limited by the fact that its oonclusion is only that the screen 
contained all the parts of the sprite with which a cxxrparison was rtade. In the 
,,..xtrere case of the screen window containing all pixels set, then an agreerrent 
would l::e found with all the sprites tested. 


SCROLLING LANDSCAPES 


Scrolling landscapes are an integral part of so fl\30Y video garres that it is worth 
a brief description of i'XYw they can best be prcrluced using White Lightning. 


The first and nost obvious rx>int is never to scroll JTOre than you have to. 
If, 
for instance, you are noving a rrountain range where the variation takes place over 
the top three characters, then cnly the top three characters need to be storErl. and 
nove:l. 


The sirrplest and rrost effective rrethc:rl of producing srooth scrolls is to sacrifice 
a colunn of the screen for transactions with the sprite being scrolled. 
Suppose 
we are scrolling a sprite of 4 or 5 screens width which uses ra,,,s 8 to 10 (3 
rows). 
Sq;,pose ~ require pixel scrolling and there is no horizontal variation in 
attributes. It doesn't really natter wtiich oolunn ~ sacrifice, far right (ooll.ffl'l 
31) or 'far left (ooluim 0), but let's, for this exanple, use oolunn 0. 
All that 
we need to do is set up a window 1 character wide and 3 characters high oo the far 
left of the landscape to have the sarre INK and PAPER colours. 
This creans that 


pixel data cannot be seen in this region. 
Use the SErAV CCITll\;llld to do this. 
To 


begin with, 31 colunns of the sprite are Pl11' to the active part of the screen 
usirig the IWBLS ccrrmand. 
If scrolling is to the left, then the dumny ool\IlTI 
should be loaded with the next colunn to the right of the sprite now 'en screen' • 
If scrolling is to the right then the col\Ml to the left of the sprite window 
should be inserted. 
The full 32 colurm screen window is ncM wrapped in the 


appropriate direction until a total of + or - 8 pixels has been accrued. 
The 


durrmy rolurm is then loaderl fran the appropriate sprite colurm and so oo. 
The 


nethcrl can be si.rrply adapted to nake the landscape wrap and is usually irrplarented 
under interrupt. 


PROGRAMMABLE SPRITES 


One of the rrost o::::mron applications of the background m::x1e is the setting of 
sprites into autonatic rrotion. 
Perhaps the chief a:l.vantage that a language has 


over a garres designer, is that the sprites thus createrl can have as much 
'intelligence' as the prograimer requires. 
A sprite can b:Junce off the edge of 


the screen and/or other sprites until a particular event, 30d then totally change 
its behaviour - possibly to follow a previously stored track. 


We have incllrled a ve.ry s.irrq;:ile listing which sets a sprite in notion, that just 
lx>unces off the edges of the screen, to give you sore idea of what is involverl. 
This sarrple pr03"ram assurres you have the deronstration sprites in naoory. 
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OCR # 6 
0 
1 
2 
3 0 VARIABLE CELAY , WAIT IEAY @ 0 00 NXJP UXJP : 
4 , S,,.SE 0 CXlL ! 18 RO; ! 32 LEN ! 6 11,T ! 0 PAPER 0 INK 
5 SETAV 7 INK : 
6 , 0016 6 PAPER 0 INK 0 OORDrn CLS 8",SE 7 0 Kr 
7 10 0 00 . " \'IHTE LIGlfl'NIN:i " LOOP O O AT ; - > 
~ 


OCR I 7 


0 8 VARIABLE PX 8 VARIABLE PY 1 VARIABALE DX l VARIABLE r:ti 
l 0 VARIABLE SP 0 VARIABLE CL 0 VARIABLE RW , PCAL PX @ ABS 
2 2 /MJD CL ! PY @ AB:i 2 /M)D RW l 00P + + 251 + SP ! ; 
3 , M)VE PX @ 56 > IF DX @ MINUS DX ! ENDIF PX @ 0 > IF NXJP 
4 ELSE DX @ MINUS DX ! ENDIF 
5 PY @ 28 > IF r:ti @ MINUS r:ti ! ENDIF PY @ 0 > IF NXlP ELSE r:ti @ 
6MINUSDY I ENDIFDY@FY@+PY ! DX@PX@+PX ! : 
7 , W RW @ RO; ! CL @ O)L ! SP @ SPN I : -> 


OCR f 8 
0 , 00T PCAL W El<X W El<X rorxRS : 
1 , 00 PCAL M)VE rorxRS W rorxRS : 
2 0 VARIABLE ICNT 2 VARIABLE ICNT 
3 , IRUN l ICNT +I ICNT @ 00P 2000 = IF -2 DX ! ENDIF 00P 4002 = 
4 IF 2 DY ! ENDIF 00P 6000 = IF 3 DY ! ENDIF 00P 8000 = IF 1 r:tf 
5 
l DX ! ENDIF 9000 = IF INT--OFF ENDIF : 
6 , 'IRY 00T ' 00 INT-00 9000 0 00 IRllN UXJP 
INT--OFF : 
7 , OCN16 0016 9999 IElAY ! WAIT 1 DX 
1 r:ti I 8 PX ! 8 PY ! -> 


OCR I 9 
0 0 ICNT ! 'IRY WAIT 0 PAPER 7 INK CLS 
1 
2 
3 
4 
5 
6 
7 


To oanpile this type, 


6 WAD <rn> 


and to execute type, 


OCN16 <Ol> 
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THE BASIC INTERFACE 


The BASIC interface was provided to increase the flexibility of the .language and 
allow the newcaner to Forth, a gradual transition. 
Sane applications are actually 


nore suited to BA.5IC rut for games writing in general, Forth is much m:,re 
appropriate and '\"1e rope that this facility will oot discourage people fran 
experinenting with Forth. 


There are four w:,rds to master at the Forth end and 3 (SR calls to nester at the 
BASIC end. 
Do not use CI.F.AR or NEW ..t,ilst in BASIC. 


The Command Level 


When White Lightning is first entered fran a CDLO start, BASIC is located teneat.h 
Forth and there is appraxi.ma:tely 1k of program space if micrcrlrives are oot in 
use. 
This is anple space if BASIC is ooly to be use::l at cxmnand level, to WAD 


and SA.VE for instance, blt if programs are to be written you will need to execute 
the RESERVE Ccmnand. 
For the ti.rre being, h::Jwever, let's just oonsider cperation 
at the a:mrand level. 
To enter BASIC fran Forth type: 


PRXi <CR> 


To re-enter Forth fran BASIC just use: 


PRINr (SR 24836 <CR> 


'lbis is the normal WARM start entry. 
Note that PRINT r.:sR must be used and oot 


RANIXJ,USE lER, or an CXJ1' OF ~ 
error may occur. 


BASIC AS A SUBROUTINE 


At the next level, lines of BASIC can be executed as i f they ~re subroutines and 
then return rra.de to your Forth program. 
The ~rd at the Forth end is ooro. 
To 
return to Forth and oontinue execution use PRINT t.:SR 30006. 


To begin with, space needs to l:e made in the dictionary for the BASIC program. 
The w:ird used to oo this is RFSERVE. 
What RESIBVE octually does, is to nake space 


in the dictionary and reset Rl\SIC' s system variables to point to this new area. 
This does nea.n, ~ver, that if a secorrl RESERVE i s OOne, without FORGETting the 
old space, then the ol d space is lost and can never l:e re-accessa:1. 
Do not 
execute a Forth OOLD start ....tiile BASIC is reserved or a RAMIOP error nay occur if 
insufficient rrerory is reserved. 
Always execute PRCX; as the next cx:rrm:md after 


RESERVE. 


As an example, try the following: 


IX:IMAL 2000 RESERVE !'RX, <CR> 


This will set up the BASIC space and then enter i t at c:cmnand rrode . 
The following 


lines of &\SIC can 11CM t:e entered: 


1000 PRINT "LINE 1000 OF BASIC" : PRINT C6R 30006 
2000 PRINI' "LINE 2000 OF BASIC" 
2010 FOR I = l ID 8 : PRINT I : NEXT I 
2020 PRINI' (SR 30006 
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JI, 
I 


~ 


After entering these lines type: 


PRINT lER 24836 


to re-enter Forth at ccmnand level. 


Let I s OCM define a word which executes sane Forth, sare BASIC, sare rrore Forth, 
sane rrore aa.src, and finally sane rrore Forth. 
To begin executing B,t\SIC at a 
particular line, all that we need to do is p.1t the line number en the stack and 
then execute 00'1'0. Try the following: 


: FBllEM • " IN FORTH " CR 1000 00I0 • " B'CK IN FORTH " <CR> 
CR 2000 OOIO • " FORTH !\GAIN " ; <CR> 


Ne,,, type FBDEM <CR> 


A rrore useful application w:>uld be to define "'°rds to handle cassette loading and 
saving. 
BASIC source is saved and loaded in the normal way £ran the reserved. 
BA.SIC area. 


Forth A.. A Subroutine 


If you're an "out and out BASIC person" you're probably rrore likely to want to 
execute Forth as a subroutine. 
To return to BASIC fran Forth use the \t,IOrd REIUSR. 


To call Forth fran BASIC use RANIXMISE lSR 30000. 
Note that oo this cccasion it 


is a RANIXMISE lSR and not a PRINT tER. 
Using the previously reserved space we 
can try another exanple. First type: 


PRCG <CR> 


to enter BA.SIC, then add the following lines: 


3000 PRINr " CALLIN:, FORTH " : RANOCMISE lER 30000 
3010 PRINr " B'CK IN BA.SIC " : ffi!Nr lER 30006 


Ne,,, type ffi!Nr lER 24836 to re-enter Forth. 


Ne,,, type: 


: BrnEM . " OOIO BA.SIC " CR 3000 00I0 • " FORTH CALLFD " <CR> 
RETUSR • " ENDIN'.i IN FORTH " CR ; <CR> 


Ne,,, type: 


BFDEM <CR> 


to see the result. 


Ne,,, type: 


FORGET FBllEM <CR> 


Paulng Parameters 


Forth variables can easily be PEEK'En and POKE 1d fran BASIC and used not oo.ly to 
pass data, bJt also to oontrol the execution of Forth. 
As an exanple, s~ we 
wished to select ooe of 4 Forth "'10rds at any oo.e tine w:i. th a call fran BASIC. 
Let 
the Forth "'10rds si.nply be • " KlRDl ", • '10R02 
10 , 
• " KlR03 ", • "W)R04 ". First 
we' 11 need a variable to pass the paraneter so type: 
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0 VARIABUl OJNIROL CDNIROL U. <CR> 


This will set up a yariable called oontrol, set it to zero and then print the 
address of the leasl::. significant byte which lE'll use to pass the information. 
For the sake of this exarrple suppose the address W:lS 50000. 
We' 11 oow use the 
CASE cxmstruct to select the w::>rd to execute. 
Use the follCMing definitions: 


: SELEX;T CASE 1 OF • " l'ORDl " EN!XlF 2 OF • " l'ORD2 " <CR> 
ENOOF 3 OF • " WJR03 " ENOOF 4 OF • " K)R04 " ENOOF <O<> 
ENOCASE Cl ; <CR> 


If the value in OJNIROL is 1 to 4, the appropriate \oOrd will te executed. 


: RUN 4000 roID IE;IN CDNIROL @ <CR> 
00P SELEX:T 00P IF RETlJSR ENDIF Cl= !NrIL : <CR> 


The BASIC program is initially entered at 4000 and ooul.d take the follO¥"ing fonn: 


4000 REM REPLACE AllOOESS 5000 WITH THE ADDRESS OF OJNIROL 
4010 PRINr " EXEX:Ul'E l'ORDl 
ro8UB 5000 


4020 PRil'lr " EXEX:UIB l'ORD2 " : (DSUB 5010 
4030 PRil'lr " EXEX:Ul'E l'DRD3 " : roBUB 5020 
4040 PRI1'lr " EXEX:UIB l'ORD4 " : rosuB 5030 
4050 PRI1'lr " FINISH " : POKE 50000, 0 : PRI1'lr !.ER 30006 
5000 POKE 5000, 1 
RANJXMISE !.ER 30000 
RETURN 


5010 POKE 5000 , 2 
RANOCMISE !.ER 30000 : RETURN 


5020 POKE 5000, 3 : RANJXMISE !.ER 30000 : RETURN 
5030 POKE 5000 , 4 : RAN!XMISE !.ER 30000 : RETURN 


Note that when final return is rrade to Forth a PRINT t:SR 30006 is used. 
If a 


RANtO-USE IBR 30006 CALL is rrade to Forth a RETUSR must be executed or the BA.SIC 
stack will l::e left corrupt.E;rl. 
To reset the stack if it has teen oorrupted, use 


PRCG to enter BASIC and then re-enter Forth with the WARM start , PRINT l6R 24836. 


'nri.s oonclu::les the section oo the BA.SIC Interface. 
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PROGRAM DEVELOPMENT 


At any one time, there are up to five areas of devel~nt: 
Forth source ccrle, 
BASIC source rode, sprites, the Forth language itself and finally, the ccnpiled 
and carplete::l program. 


Forth Source 


As previously discusSOO under the section on e1iting, Forth SOurce is divide1 into 
screens, each of 512 bytes in length. 
Each screen can be individually loaderl, 
saved and cx:rnpiled in any order required. 
Screens can even be saved and then 
loaded b3.ck into different screens. 
The real cdvantage of this canes when you' re 
writing really large programs. 
As sprite space l:ecanes large, it will w::>rk dcMn 
over the higher screens and this can be clearly seen when an attempt is made to 
List them. Dcxl't CLFAR these screens or the sprite data will l:e lost! 


If really large programs are required and sprites have over-run the top screens, 
then programs can be o::rtpiled a few screens at a t:irre, loading each tirre into the 
available screens, ccnpiling and then loading the next section . .. Of course, you 
don't neerl to Load the sprites until o:rrpilation is cx:nplete, tut it's useful to 
have the facility just in case. 


To save Forth source you' 11 ooed to consult Table 1, the table of Screen 
Ad:lresses. 
If, for instance, you wanted to save screens 6 to 11, then the start 
address "'°uld be 52224 decimal and the length, just 6 tines 512. 
Type 6 512 • • 


<CR> to find this figure, which is 3072. 
To save the source, type PRCXi to enter 


BASIC and then type: 


SAVE 
11filename 11 CX)DE 52224,3072 


To re-enter White Lightning, type PRINT llSR 24836 to do a WARM start. 


To Load the source, either type Y in response to the IDAD OOURCE Y/N prarpt at the 
beginning of the session, or exit to BASIC using PROO, then type: 


IDAD "filename" alDE 
where filenarre is optional. 


If you want to Load. the cxxle into a different screen area fran that in which it 
was Saved, type: 


:r.o.»J) "filenane" 00DE start, length 


where start is the Mdress of the screen to be loade:1, and length is the number of 
screens to be loaded multiplied by 512. 
Again, White Lightning should be 
re-entered with a PRINT l.SR 24836. 
Do not use RANIXMISE tER 24836 or an oor OF 


s:::::Rm1 error may occur. 


BASIC Source 


Before BA.5IC source can be used in White Lightning programs, the user must execute 
a RE.SE.RVE to rrake space for the BZ\SIC program. 
To reserve, for exarrple, lK, type: 


I:ECIMAL 1024 RESERVE. 
This will allocate 1024 bytes for BASIC source oode within 


the dictionary. If at sare later stage you execute a second reserve the previous 
1024 bytes are not reclai..ned, so if you find you have not allocated enough space, 
Save the BASIC source, FORGET all previous definitions, execute a OOLD srART, and 
start the cx:npilation fran scratch. Yoo can nC7N' do a second RE.SERVE. 
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ro save Bl\SIC source, type PRCX:; <Cl.> to enter BASIC if you ' re not alrE!OO.y there, 
then just type SAVE "filenarre" as nonnal and re-enter White Liqhtninq with PRINI' 
:ER 24836 . 
Likewise, source can l:e reloaded by enterinq Bl\SIC with a PRCX;, using 
tDAD "filenaire" and then re-entering Forth with a PRINT lER 24836. 


Sprites 


Sprites can l:e Saved fran Whi te Lightninq and then re-Loaded into White Liqhtninq, 
b.Jt sprites saved bv White Lightninq, cannot be loaded into the sprite develoµnent 
software which requires the additional array information preceedinq sprites which 
is oot SA.VEd by White Liqhtninq. 
Sprite developnent should always be done usinq 


the develoµnent oof tware, bJ.t if you do wish to save the sprites for later rrerqinq 
then do the follOirlinq: 


1. 
Find the start of sprites I,; typing SPST @ U, 


2. 
Find the l.enqth to save I,; typing SPND @ SPST @ - l+ U. 


3. 
Note the start and lenqth, then return to IW3IC usinq PROO. 


4. 
SAVE using SA.VE "filename" CODE start, length. 


5. 
Re-enter White Lightning using PRINr !ER 24836. 


Merging Sprites 


Two blocks of sprites can be rrerqed toqether in the nein program usinq the 
follc:Ming procedure: 


1. Make a note of the SPST and SPND values of the secoOO block to l:e 
rrerqed. 
These are displayed by the sprite developnent software. 


2. 
Load the nein White Liqhtninq packaqe and then load the first block 
of sprites in response t.o the "IOAD SPRITES Y/N" pranpt. 


3. 
load source as required and once in the main program relocate 
the first block of sprites cbwnwards by the size of the second 
block. 
Suppose the decimal values for SPST and SPND of the second 
block ...,re 60000 and 65280 respect ively, then type:- 


00::IMAL 60000 65280 - SPST @ + U. <CR> 


(The I:ECIMAL is oot required if you are already in DEX::IMAL rn::xle). 
This will calculate the new start after relocation. 
It is well ~rth 
checking that this will not run over your source axle, so here is a 
quick calculation that will tell you if you have enouqh space. 
You 0000. to knCM th~ highes t screen nurnl:er that you intend to use, for 
example screen 18. 
Type: 


18 512 * 49664 + U. <CR> 


This wil l print the first free byte after screen 18. 
So lonq as 
this result is lower than the new sprite start after relocation you 
can procee1. 
Again, usinq the previous exal'rl)le where the block to l:e 
rrerqed has SPST and SPND of 60000 and 65280 respectively. the line 
t.o t ype is : 


00::IMAL 60000 65280 - MLEN ! RELOCATE <CR> 
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The relocate cx:mnand uses the value held in MLEN as the relocation 
length, a negative value, as aoove, relocates cbwnward and a p:isitive 
value up,,ard. 


4. 
Before loading the second block of sprites, the values of the new 
SPST and SPND should be calculated and ooted. 
Type: 


SPST @ U. SPND @ 65280 60000 - + DUP SPND I U. <ffi> 


Take a oote of these tv.U values. 
If the previous steps have l::een 
carried out oorrectly the second numl::er ( the new SPND) should be the 
sarre value as the old SPND t:efore relocation. 


5. 
Type: PR(X; <CR> to exit l::a.ck to BASIC then type IDAD ,rn O)l)E. 
The 
array of fX)inters will be ignored b.lt the sprites will be loaded. 
This assurres that this second block of sprites was also saved using 
the sprite daveloprent software. 


6. 
Type PRINI' l.SR 24836 to re-enter Forth and your sprites should l:e 
merged. 
Note that if a sprite number used in the second block has 
also been used in the first block, that only the first occurrence 
will t:e found. 
If the first occurrence is de:Stroyed using WIPE or 
OOPRITE, then the second occurrence will t:e found. 


Extending The Forth Itself 


Ore of the teauties of the Forth language is that it is extendible, so if you've 
added a fe,; of your o,m cx:rrrrands which you would like to becone a pennanent 
feature of your c..ustanised rersion, you will need to nake a oopy. 
For this 
reason, oo attempt has teen made to protect the software; b.it ~ 00 appeal to 
users oot to take ad.vantage of this facility to pirate the program. 
Piracy pishes 


up the price of software to genuine users, so if you're b:>ught a genuine copy, 00 
yourself a favour and keep the price of your future software affordable. 
Copying 
the rranual, lx:lwever, will result in inmediate court action and a re,,,ard will be 
paid to anyone offering information leading to the successful prosecution of 
offenders. 


To save the Forth use the follCMing procedure: 


1. 
Type: WARM-XDLD <m> to anbed the cxmnands. 


2. 
Type: HERE 24832 - l+ U. <m> to print the length to be Saved. 


3. 
Type: ma; <ffi> to enter 81\SIC. 


4. 
Save using SA.VE "FORTH" OJDE 24832, length. 


5. 
Re-enter using PRINr USR 24836. 


To use the arrended version, I.DAD White Lightning as oormal, exit using PRCG, IDAD 
the new Forth CNer the old Forth and execute a Cold start using 24832. 


Oasis rrak.e oo undertakings to oopport c..ustanised rersions, and rrak.e oo guarantee 
as to the success of the cperation. 
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Complied and Completed Programs 


Once the program is fully debJgged and running, a final run-time version can l::e 
proiuce:i. 
This is the ooly form in which programs generated fran White Lightning 
can be marketed. 


If the program rrakes use of the foreground/background facility, ZAPINT should l:e 
typed, if not, then ZAP should be typed. 
The length of the canpiled program is 


then displayed until a key is pressed and oontrol returned to BASIC to make a 
copy. 


The final program should l:e save:l using: 


SAVE "filename" 24832, length 


and executal. using RUNT U3R 24832. 
Do not use RANIXMISE U3R 24832. 


Remember that a lot of run-time software is save:! with your f inal code, so even if 
your program is only two lines long, 
the resulting program will te pretty large. 


Screen 
NIJllber 


l 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 


TABLE 1. 


Table of Screen Numbers and Addresses 


Start 
Address 


49664 
50176 
50688 
51200 
51712 
52224 
52736 
53248 
53760 
54272 
54784 
55296 
55808 
56320 
56832 
5i344 
57856 
58368 
58880 
59392 
59904 
60416 


Each screen used for editing 
into consists of 
8 lines x 64 characters 
= 512 bytes. 


Therefore, if you have only 
edited into screens 6-9, 
then there is no need to save 
ALL of the screens 1-22 
since you only need to save 
fran 52224 to 54271 (end of 
screen 9), i.e. 2K bytes. 
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FUNCTION KEY SUMMARY 


KEY 


,A 


B 


C 


D 


Activates the ATIRIBUI'E switch. 
Press 1 to set switch 00. 
Press 0 to set switch OFF. 


Activates the ERIGHT variable. 
Press l to set ERIGHT to CN. 
Press O to set ERIGHT to OFF. 


Activates the PAPER variable. 
Press any key between O and 7 to activate the colour indicated 
above the key. 


Activates DIRECT mTA INPl1I'. 
Aocepts 8 bytes of data, one byte at a time, foll<J'wed. by EN!'ER, via 
the keyl:oard, to the I;XJSition en the sprite Screen indicate::l by 
the cursors. 
Inputted data must l:e in the range O to 255 Decimal 
or, HOO to HFF HEX ( the character H must precede Hex entry). 


N::>TE: 
If AttribJte switch = 1, then the four current attributes will 
be use:i at the sarre position as <Ell. 


E 
Activates the s::REEN FUICl'IONS. 
Yoo will be given three q,tions; press 1, 2 or 3. 


1 INVERT 
Option 1, INVERr, sets all O bits to 1 and all 1 bits to 0, 
in a window whose length is held in the "Sprite length" 
variable and whose height is hald in the 11Sprite height" 
variable. 
The inversion will take place £ran the positioning 
of the sprite screen cursors, i.e. at the intersection of an 
imaginary line drawn £ran each cursor. 


2 MIRROR 
Option 2 MIRROR, 'Flips' a window whose height is held in the 
"Sprite height" variable and whose length is held in the "Sprite 
length" variable. 
The Mirroring will take place about the 
vertical centre of the screen window. 


3 MIRROR ATIRIEUl'ES 
Option 3 MIRROR ATIRIEUl'ES, 'Flips' the attributes in a windc:M" 
whose height is held in the "Sprite height" variable and whose 
length is held in the "Sprite length" variable. 
The Mirroring of 
Attributes will take place about the vertical centre of the screen 
window 


F 
Activates FIASH WINI:Oi. 
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Flashes the current screen window whose height is held in the 
SPRITE HEIGHT variable and whose length is held in the SPRITE r=! 
variable. 
The Flash will take place at the position of the sprite 
screen cursors. 


Flash is used to check the position of the sprite screen cursors, 
to check that the lle:ight and length parameters are as require:i or 
to dleck that the window is correctly positioned. 


G 


H 


Activates GET SPRITE function. 
Gets a sprite of the dimensions held in the "Sprite height" and 
"Sprite length" variables, using the number held in the "Sprite 
Number" variable and at the window indicated by the sprite screen 
cursors - and stores it in rraoory. 


Wl'E: 
If the Attribute switch = 1, the sprite and attributes 
are stored; if the Attribute switch = O, then any Attributes will 
be ignored.. When a sprite is first defined with Attribute 
switch = 0 the attribute data will probably be garbage. 


Activates the SPRITE HEIGHT Variable. 
Permits the input of the height of a sprite window £ran 1-15. 


Activates the ATIRIBIJIE [U,1P function. 
Places the four Attributes set in the four Attribute Variables, 
to the sprite screen, at the position indicated by the sprite 
screen cursors - with a resolution of one character. 


NJI'E: 
This function is independant of the Attribute Switch, e.g. 
to place Attrib.Jtes at position x=4, y=4: 
rx,sition sprite screen 


cu.rsors at X=4 and y=4, then set the four attributes as required 
(you can then set the Attribute switch to 0 (OFF) if you like) 
and press I. 


Activates the rrove OIR$ ~ 
'IO SPRI'IE 9:REEN function. 


Durps the bit pattern set in the QiR$ S(Jl to a character square 
in the sprite screen, indicated by the sprite screen cursors. 


NJI'E: 
If the Attribute Switch = 0, no Attributes will nove with 
the pattern. If the Attribute switch = 1, then the Attributes 
held in the Attribute Variables will nove with the pattern. 


K 
Activates the M:JVE SPRITE OCREEN CllARl\CTER '.ID Q!R$ S(Jl 
function. 
Picks up the Character Square indicated by the Sprite Screen 
Cursors, into the Offi.$ $. 


NJI'E: 
ATIR • 0 ignores Character Attrib.ites. 
ATIR • 1 takes the 


Attributes of the character and loacls them into the AttribJte 
Variables. 


L 
Activates the SPRITE LEN:;'l'H variable. 
Permits the input of the length of a Sprite Windaw fran 1-15. 


M 
Activates the Sprite Functions. 
You will re given three cptions which act in the sarre way as the 
'9:REEN FUCTIONS E 1 , except that these functions q:,erate on 
the sprite in rretr)ry only and have no effect directly on the 
screen. 


N 
Activates the No, negative response to CY/N) questions. 


0 
Activates the Sprite t.cgic functions. 
You will be given three cptions. 
F.ach cption GETS an area of the 
sprite screen, the diITensions of which are specifie:i as those of 
the define:1 sprite, having a top left-hand corner at the sprite screen 
cursor positions and logically GETs the data into the define:1 sprite - 
- whose number is in the Sprite NumlJer Variable. 


84 


1!1 


IDI'E: 
ATI'R = 0 leaves the attributes of the sprite as they are. 
ATIR = 1 takes the attributes fran the screen and places then 
into the sprite. 


1 GE'IORS, CRs the screen data with the pre-defined sprite, and 
leaves the result in the sprite ( screen display unaffected> . 


2 GETXRS, XORs the screen data with the data of a pre-defined 
sprite, and leaves the result in the sprite, (screen 
display unaffected.). 


3 GETNDS, ANOs the screen data with the data of a pre-defined 
sprite, and leaves the result in the sprite (screen display 
unaffected). 


P 
Activates the Pl1l' functions. 
Yoo will t:e given four q,tions. 
Each cption Pl1I's a sprite 


whose numter is specified. in the variable "Sprite Number" ooto 
the sprite screen, having a top le ft-hand corner at the sprite 
screen cursor p:>sitions. 


mrE: 
ATIB. = O leaves the Screen Attributes unaffected.. 


ATIR = 1 PU'I's sprite Attributes to the sprite Screen. 


l PUTBIS is a straightforward PUT, placing data directly to 
the sprite screen, destroying anything that is on that part of 
the screen (Sprite unaffected>. 


2 PlJIORS, CRs the sprite data with the data on the sprite screen, 
leaving the result oo the screen (Sprite unaffected). 


3 Pt.mCRS, XORs the sprite data with the data on the sprite screen, 
leaving the result on the screen (Sprite unaffected). 


4 Pl11Nll:i, ANDs the sprite data with the data on the sprite screen, 
leaving the result oo the screen (Sprite unaffected). 


a 
Activates the CLF.AR CHR$ S(Jl function. 
Sets all CHR$ S(Jl bits 
to zero. 


SYMBOL Activates the CLF.AR SPRITE s::REEN function. 
Clears the sprite 


SHIFT 
screen of all data and attributes. 


Q 
( <=) 


R 
Activates the OOTATE SPRITE function. 
Rotates a sprite, in nerory, by 90 degrees, leaving the original 
sprite unaffected. 
The new Rotated sprite must be given a ~ 
sprite number, as asked for . 
Attributes are autanatically 
Rotated with the pixel data. 


S 
Activates the SPRI'IB t,U,iBER variable. 
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Penn.its the defining of sprites and asks for a sprite number in 
the range l to 255 


WI'E: 
If a sprite to be defined is given an existing sprite 


number, a 'filBrning is displayed, cdvising you of this fact. 
The 
existing sprite, or the new sprite, are in no way oorrupted. 


T 
Activates the 'lFST SPRITE function. 
Performs a test oo the sprite whose number is held in the "Sprite 
Nllllber" variable, and does the follc:Ming: 


1. Places the sprite height into the "Sprite height" variable. 
2. 
Places the sprite length into the "Sprite length" variable. 
3. 
Places the address in nemry of where the sprite data starts, 
into the 
11Sprite11 variable. 
4. 
Places the cddress of the start of sprite space into the variable 
"SPST". 


u 


V 


5. 
Places the oodress of the end of sprite space into the 
variable 11SPND 11 • 


6. 
Calculates the remaining nerory available for sprite 
storage and places it into the "Marory Left" variable. 


NJTE: 
The screen display of these variables will t:e updated 
if necessary. 


Activates the PICK tD? ATl'RIBtJl'ES function. 
Picks q:, the attrib.ttes of the character fran the sprite screen, 
indicated by the p:>5,ition of the sprite screen cursors and 
Loads than into the four Attribute variables. 


Activates the FtA5H variable. This is ooe of the four attributes. 
Press 1 to p.it switch CN. 
Press O to i;,,t switch OFF. 


w 
Activates the WIPE SPRITE function. 
Wipes the sprite indicated by the "Sprite numl::er" variable 
totally fran rremory. 
All other sprites stored in rrenory belCM 
that sprite are JTOVed q, to fill the space previously 
occupied by the Wiped sprite. 


X 
Activate the INK variable which is ooe of the four attributes. 
Press any key bet;,.,een O and 7 to set the oolour indicated 
above the key. 


Y 
Activates the YES, positive res{X)rlse to (Y/Nl questions. 


Z 
Activates the pre-de£ ined ARCADE OiARACTER function. 
Place a pre-defined Arcade Character to the sprite screen. 
The top left hand oorner of the character is indicated by 
the sprite screen cursoi:-s. 
Input a number between 1 and 167 
foll"""'1 by ENI'ER. 


N:)TE: 
Each character, with its number, can be seen on the Demo B 
tape. 
A list is given at the back of this section. 


NOT 
.Activates the SAVE SPRITE.S 'ID TAPE facility. 


!SYMBOL 
SHIFT 
SI 


Place a suitable cassette in your cassette recorder and 
position as desired. 
Press ?Ur, enter your filename (1 to 8 


characters). 
The program will save three groups of data; 


an array and two sections of cede. 
After SAVEing, you will re asked to rewind the tape and VElUF'i - 
be sure to coly press PLAY on your cassette recorder. 
If the programs \'ERIF'i, the Sprite Develq;nent Program will 
return. to camand level with the Text Line cleared. 


WI'E: 
If the program breaks tecause of failure to VERIFY, 


type ooro 3 and execute a W7-\ru-l srART; your data will not re lost. 
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{SYMBOL 
SHIFT 
J) 


Activates the IDAD SPRI'IBS FR0-1 TAPE facility. 
Place tape in your cassette recorder. 
Press SYMOOL SHIFr J 
and press PLAY on the cassette recorder. 
Three groups of data 
will load. 
When loaded, the Text Line will clear and the 
program will resune. 


OOTE: 
Any sprites in rrem::,ry will be destroyed \fflen this cx:mnand 


is executed. 


& 
Activates the l-OVE OIR$ CURS)R 1 place to the left - non- 
destructive. 


Activates the M)VE OIR$ ~ 
CURroR 1 place down - oon-destructive. 


7 
Activates the MJVE QIR$ ~ 
CURS'.)R 1 place up - non-destructive. 


Activates the KlVE QIR$ SQ< CURS)R 1 place to the right - 
non-destructive. 


9 
Activates the SET OIR$ at current position. 


Activates the CLE'AR am$ ~ 
at current p:,sition. 


% 
Activates the KlVE SPRITE OCREEN CUR9'.lR 1 place to the left. 


{SYMBOL 
SHIFT 
&) 


& 
Activates the !OVE SPRITE OCREEN CUR9'.lR 1 place oown. 


{SYMBOL 
SHIFT 
6) 


Activates the l-OVE SPRITE s:REEN CURroR l place q;,. 


{SYMBOL 
SHIFT 
7) 


{~YMBOL Activates the KlVE SPRITE OCREEN ClRS:JR 1 place to the right. 


SHIFT 
8) 


< 
Activates the RELCCATE SPRITES function. 


(SYMBOL Allows the user to nove the sprite data about in llEl'l'Ory, 
SHIFT 
bebeen the top of the Sprite Generator Program and address 


A) 
65520. 


BREAK 
and 
SPACE 
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e.g. 
a positive m.unber i.e. 50, noves the data 50 bytes q;:, 
in rrerory. 
A negative .number i.e. -50, noves the data 50 


bytes oown in nerory. 
CAUl'ION - use this function with care. 


Activates the PLACE SPRI'JE IN'lO SPRITE WIN1XM function. 
'l"nis allows you to place a sprite of snaller dimensions in to 
a serond sprite of greater dimensions, at a position of KM, 
OOL in the greater sprite in ITSOC>ry - the snaller sprite is 
left unaltered. 


NJI'E: 
M-m = O, AttribJtes of snaller sprite ignore:!. 
AT'lR = 1, AttribJtes of snaller sprite taken and placed with 
sprite. 
Three q:,tions are given: 


lGEI'BLS 
GETs the snaller sprite directly into the window of the larger 
sprite. 


2 GE'IDRS 
Gers the snaller sprite and 00s it into the window of the 
larger sprite. 


3 GEl'XRS 
GETs the snaller sprite and l<DRs it into the window of the 
larger sprite. 


4 GE'JNr:G 
GETs the snaller sprite and ANDs it into the window of the 
larger sprite. 
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ARCADE CHAR- 
ACTER NUMBER 


1- 
8 


9- 11 


12 


13- 20 
21- 22 
23- 25 
26- 33 
34- 44 
45- 54 
55- 62 
63- 67 
68- 70 
71- 74 
75- 84 
85- 88 
89- 98 
99-107 


108-117 
118-130 
131-136 
137-141 
142-148 
149-152 
153-158 
159-167 


THE WHITE LIGHTNING ARCADE 
GRAPHICS LIBRARY 


Asteroids Spa.ce Ships 
Asteroids 
Asteroids Flying Saucer 
Pac-Men 
Pac-Men Gh::>sts 
Fruit 
Pac~ Maze Parts 
Assaul t Course type games 
Defender type grures 
Defender type landscapes 
Space Invaders 
Space Invader Bases 
Space Invader Guns etc. 
City Banber type grures 
Lunar Lander type grures 
Frogger type grures 
Centipede type grures 
war type grures 
Donkey Kong type grures 
Space War type grures 
Explosions 
BU3-Eya:I Mcnsters 
Robots 
Adventure type games Treasure 
Zaps 


WHITE LIGHTNING DEMONSTRATION 
SPRITE LIBRARY 


SPRITE 
DESCRIPTION 
INK 
PAPER 
LENGTH HEIGHT 


NUMBER 
COL 
COL 


1 
VINTPGE CAR 
4 
0 
4 
2 


2 
VAN 
5 
0 
4 
2 


3 
OOl\GSTER 
6 
0 
4 
2 


4 
oo:K 
6 
0 
3 
3 


5 
I:WOR 
7 
0 
2 
4 


6 = 
5 
0 
4 
2 


7 
SPIDER #1 
5 
0 
4 
5 


8 
SPIDER 12 
5 
0 
4 
5 


9 
'IOP OF '.!RAIN 
4 
0 
11 
2 


10 
RAII.Wl\Y '.IRPCl< 
6 
0 
8 
1 


11 
~~ 
1,5 
7 
4 
l 


12 
OASIS r= 
5, 7 
0 
12 
4 


13 
T.V. 
2 
0 
15 
12 


14 
'IOP OF RAII.Wl\Y CXll'CII 
5 
0 
10 
2 


15 
SPl'CE SHIP 
0 
5 
4 
2 


16 
SIIA[Oi OF SPl'CE SHIP 
5 
7 
4 
1 


17 
IARGEWALL 
2, 7 
7 
8 
2 
18 
'.!RAIN lfiEEI.5 #1 
4, 7 
0 
ll 
1 
19 
~ 
lfiEEI.5 #2 
4, 7 
0 
11 
1 
20 
'.!RAIN lfiEEI.5 t 3 
4, 7 
0 
11 
1 
21 
'.!RAIN lfiEEI.5 t 4 
4, 7 
0 
11 
1 
22 
RAIIWAY ClJl>CH fl 
7 
0 
10 
1 
23 
RAIIWAY ClJl>CH f 2 
7 
0 
10 
1 
24 
INVADER O 003REES 
6 
0 
2 
2 
25 
INVADER 90 003REES 
6 
0 
2 
2 
26 
INVADER 180 003REES 
6 
0 
2 
2 
27 
INVADER 270 003REES 
6 
0 
2 
2 
28 
FPCE WITH HAT tl 
4 
0 
4 
3 


29 
Fl'!CE WITH HAT f 2 
4 
0 
4 
3 
30 
'NfITE' 
5, 7 
0 
7 
2 


31 
'LIGH'ININ.' 
5, 7 
0 
10 
2 


32 
LIGlfl'NIN. BJLT 
5 
0 
13 
4 
33 
CRAB 
4, 7 
0 
5 
3 
34 
LrnAR LIINDm 
7 
0 
6 
4 
35 
RADAR #1 
7 
0 
2 
1 
36 
RADAR #2 
7 
0 
2 
1 
37 
RADAR #3 
7 
0 
2 
1 
38 
RADAR #4 
7 
0 
2 
1 
39 
RADAR #5 
7 
0 
2 
1 
40 
RADAR #6 
7 
0 
2 
1 
41 
RADAR i7 
7 
0 
2 
1 
42 
RADAR f8 
7 
0 
2 
1 
43 
EXPWSION 
7 
0 
2 
2 
44 
LUU\R SURFPCE 
6 
0 
15 
1 
45 
ROrATIN. BALL U 
6 
0 
4 
4 
46 
ROrATIN. BALL #2 
6 
0 
4 
4 
47 
ROrATIN. BALL #3 
6 
0 
4 
4 
48 
ROrATIN. · BALL i4 
6 
0 
4 
4 
49 
=-IDYS U 
4 
0 
3 
12 
50 
=-mYS #2 
4 
0 
3 
12 
59 
''IRY 'lHIS I 
4 
0 
8 
1 
60 
'WilllOUT I 
4 
0 
8 
1 
61 
'IBCM' 
5 
0 
5 
1 
251 
wrn::rn:; BALL n 
0 
6 
3 
3 


252 
BJON:IN. BALL t2 
0 
6 
3 
3 


253 
BJUN::IN. BALL t3 
0 
6 
3 
3 


254 
WUICIN. BALL #4 
0 
6 
3 
3 
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Fig-FORTH GLOSSARY 


This glossary contains all of the word definitions in Release 1 of Fig-FOR'IH. 
The 
definitions are presented in the order of their ASC:II sort and are reprcrluce:i 
courtesy of the FORTH INIBREST G<OUP, P.O. IDX 1105, SAN CARIDS, CA 94070. 


The first line of each entry shows a syml:olic description of each action of the 
procedure oo the parameter stack. 
The: symlx>ls indicate the order in which input 
paraneters have been placed oo the stack. 
Three dashes "---" indicate the 
execution point; any paraneters left on the stack are listed. In this notation, 
the top of the stack is to the r ight. 


The symbols inclu:le: 


addr 
nerory a:ldress 
b 
8 bit byte (i.e. hi 8 bits zero) 
c 
7 bit ASCII character Chi 9 bits zero) 
d 
32 bit signErl. double integer, rrost significant p:irtion with sign 
on top of stack 
f 
l:xx>lean flag. 
0 = false, non-zero= true. 
ff 
boolean false flag - 
O 
n 
16 bit signed integer number 
u 
16 bit unsigne:i integer 
tf 
b:x>lean true flag = oon-zero 


The capital letters en the right show definition characteristics: 


C 
May oo.ly be used within a oolon definition. 
A digit indicates 
number of nerory 00.dresses used, if other than ooe . 
E 
IntendErl for execution coly. 
ID 
Level zero clef ini tion of FORTH-78. 
LI 
Level 1 definition of EORTH-78. 
P 
Has precedence bit set. Will execute even when o:mpiling. 
U 
A user variable. 


Unless otherwise ooted, all references to nmnbers are for 16 bit signErl integers. 
The high l:r{te of a number is en tq:> of the stack, with the s i gn an the left:m::>st 
bit. 
For 32 bit signErl dc>uble numbers, the nost significant bit (with the sign) 


is m top. 


All aritlvretic is .i.nplicitly 16 bit signed integer nath, with error and underf l ow 
indication specified. 


Wl'E: 
All references to disc in this (X)C."U[(entation can be rea:i as references to 


the disc simulation area in neoory fran C200H to FO00H, which are treated as a 
very limited disc capacity by White Lightning, and do not in any way change the 
q,eration or description of any of the FCRTH ~rds definErl in this docurrentation. 
ro ?01' use mo, rRl or oo. 


n a:ldr - 
ID 


Store 16 bits of n at a:ldress. 
Pronounced "store". 


_ICSP 


Save the stack EX>9ition in CSP. 
Used as part of the carpiler security. 


ill - 
d2 
ID 


Generate fran a double m.nnber dl, the next ASCII dlarater "-Tiich is placed in an 
output string. Result d2 is the qootient after division by eASE, and is 
iraintained for further processing. 
Used bet>ieen <t and t>. 
see IS. 


I > 
d -- addr oount 
ID 


Tenninates mmeric cot.put oonversion by drq;:ping d, leaving the text a:ldress and 
character oount suitable for 'lYPE. 


jjBUF 
--n 


A oonstant returning the number of disc b.lffers allocated. 


lfS 
ill - 
d2 
ID 


Generates ascii text in the text output bJffer, by the use of I, until a zero 
double number results. 
Used bet"""° <I and f>. 


- 
addr 
P,ID 


Used in the form: 
' nnnn 


Leaves the paraneter field aidress of dictionary w::>rd nnnn. 
As a cx:npiler 


directive, executes in oolon definition to cxrrpile the OOdress as a literal. If 
the ~rd is oot found after a search of CDNmXT and aJRRmI', an apprq;>riate error 
message is given. 
Pronounced "tick". 


P,ID 


Used in the form: 
Ccccc> 


Ignore a aament that will be delimited by a right parenthesis oo the sane line. 
May occur during execution or in a oolon-definition. 
A blank after the leading 


parenthesis is required. 


( . " ) 
C+ 


:,e th1:~~ct:~~~, ae~!~OO S: . : which transnits the following in-line text 


(:CODE) 
C 


The run-time procedure, ccnpiled by ;OODE, that re-writes the code field of the 
lll>St recently defined v.0rd to (X)int to the following rrachine code sequence. 
See 


rCDDE. 


(+LOOP} 
n -- 
C2 


"the run-time procedure cx:inpile:i by +UX)P, which increments the loop index by n and 
tests for loop o::mpletion. 
See +IOOP. 
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I, 


(ABORT) 


Executes after an error when WARNit-J:; is -1. This \liOrd normally executes AEORT, 
but may re altererl (with care) to a user 1 s alternative procedure. 
See WAR.NIN:;. 


(00) 
C 


The run-time procedure cx:rrpiled by 00 which rroves the loop control paraneters to 
the return stack. 
See 00. 


(FIND) 
oodr l 
addr2 -- 
pfa b tf I olc) 
addrl addr2 -- 
ff 
(tadl 


Searches the dictionary starting at the narre field a:ldress a:ldr2, matching to the 
text at crldrl. 
Returns parameter field a:idress, length byte of narre field and 
b:X>lean true for a gocd natch. If no natch is found, only a b:x>lean false is 
left. 


(LINE) 
nl n2 -- 
addr oount 


Coovert the line number nl and the screen n2 to the disc blffer a:ldress containing 
the data. 
A count of 64 indicates the full line text length. 


(LOOP) 
C2 


The run-time, proc-edure cx:rrpiled by I.CX)p which increments the loop index and tests 
for loop ccrrpletion. 
see IOOP. 


!NUMBER) 
dl ,.Jdrl -- 
d2 ,.Jdr2 


Coovert the ASCII text begiming at ,.Jdrl + l with regard to BASE. 
The new value 


is accumulated into double number dl, teing left as d2. 
Addr2 is the address of 
the first I.Hloonvertibl e digit. 
Used by N!Nll'R. 


nl n2 -- 
prcrl 
ID 


Leave the signed prcxluct of ~ 
signed numbers. 


*/ 
nl n2 
n3 -- 
n4 
ID 


Leave the ratio of n4 = nl *n2/n3 where all are signed numbers. 
Retention of an 


intermediate 31 bit prcxiuct permits greater accuracy than would be available with 
the sequence nl n2 • n3 /. 


"/MOD 
nl n2 
n3 -- 
n4 n5 
ID 


Leave the qootient nS and remainder n4 of the q>eration nl*n2/n3. 
A 31 bit 
intermediate product is used as for * /. 


+ 
n1 n2 -- 
sum 
ID 


Leave the sum of nl+n2. 
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• 


+! 
n addr -- 
ID 


Adi n to the value at the a:l.dress. 
Pronounced "plus-store". 


nl n2 
- - 
n3 


AR;:,ly the sign of n2 to nl, which is left as n3. 


+l!DF 
addrl -- 
addr2 
f 


Advance the disc bJffer address .::rldrl to the a:idress of the next l::uffer crldr2. 
Boolean f is false when addr2 is the bJffer presently p:>inted to by variable 
PREV. 


+ LOOP 
nl -- 
(run) 
addr n2 
- 
( canpile l 


Used in a oolon-definition in the form: 
IXl 
•• • 
nl 
+IOOP 


P,C2,I.O 


At -run-t.irre, +IOOP selectivel y oontrols branching tack to the corresponding ro 
based oo nl, the loop index and the loop limit. 
The signed increment nl is added 


to the index and . the total <:XJJpa.red to the limit. 
The branch b3.ck to ro occurs 


until the new index i s equal to or greater than the limit (nl>O>, or tmtil the new 
index is ~ 
to or less than the limit (nl<O). 
Upon exiting the loop, the 


paraneters are discardetl and the execution oontinues ahead. 


At cx:rnpile ti.ne, +IOOP ccrnpiles the run-tine \toOrd (+IOOP) and the branch offset 
cxmputed fran HERE to the address left co the stack by 00. 
n2 is used for ccrrpile 


time error checking. 
· 


+ ORIGIN 
n --- 
addr 


Leave the rrerrory address relative by n to the origin pararreter area. 
n is the 


minimum address unit, either byte or w:::ird. 
This definition is usErl to access or 


lbiify the b:>ot-~ param:!ters at the origin area. 


n -- 
ID 


Store n into the next available dictionary rrem:>cy cell, advancing the dictionary 
p::,i nter. 
( ccmna) • 


nl n2 -- 
diff 


Leave the difference of nl- n2. 


ID 


Cootinue interpretation with the next screen. 
(Pronounced next-screen). 


nl 
nl 
nl 
(if zero) 


nl nl 
(non-zero) 
ID 


Repr crluce nl only if it i s oon-zero. 
This i s usually usa::l to ccpy a value just 


before IF, to eliminate the need for an ELSE part to drop it. 
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-FIND 
- 
pfa b tf 
!found) 
ff 
(not found) 


Aa::epts the next text w:Jrd (delimited by blanks) in the input stream to HERE, then 
searches the OONl'EXT and then OJRRENI' vocabularies for a 11\3.tching entry. 
If 


found, the dictionary entry's pararreter field address its length byte, and a 
boolean true is left. Otherwise, only a toolean false is left. 


-TRAILING 
addr nl -- 
addr 
n2 


Adjusts the character count nl of a text string beginning a:idress to suppress the 
output of tra iling blanks. 
i.e. the char acter s at a:idr+nl to addr+n2 are blanks. 


n -- 
ID 


Print a number fran a signe::1 16 bit two's carplenent value, converted according to 
the nUireric PASE. 
A trailing block follows. 
Pronounced "dot". 


P,ID 


Use:i in the form: 
• " cccc " 


CCll{)iles an in-line string cccc (delimited by the trailing "), with an execution 
procedure to transroi t the text to the selected output device. If executed ootside 
a definition, • " will inroodiately print the text until the final ". 
See (. "). 


.LINE 
line scr -- 


Print oo the terminal device, a line of text by its line and screen number. 
Trailing blanks are suppressed. 


.R 
nl 
n2 -- 


Print the number nl right aligned in a field whose width is n2. 
No following 
blanks printed. 


I 
nl n2 -- 
quot 
ID 


Leave the signed qootient of nl/n2. 


/ MOD 
nl n2 -- 
ran quot 
ID 


Leave the remainder and signed qootient of nl/n2. 
The remainder has the sign of 


the dividend. 


0 1 2 3 
-n 


These srall numl:ers are used so often, that it is attractive to define than by 
name in the dictionary as oonstants. 
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O< 
n 
- 
f 
ID 


Leave the true flag if the number is less than zero (nega~ive), otherwise leave a 
false flag. 


n 
- 
f 
ID 


Leave a true flag if the rn.unber is equal to zero, otherwise leave a false f l ag. 


OBRANCH 
f 
- 
C2 


The run-tirre prcx:edure to conditionally branch. 
If f is false (zero), the 


following in- line pararreter is cdded to the interpretive pointer to branch ahea:l 
or back. 
conpiled l::r{ IF, l.Nl'Il. and mILE. 


1+ 
nl -- 
n2 
Ll 


Incrarent nl by 1. 


2+ 
nl - - 
n2 
Ll 


Leave nl incremented by 2. 


21 
nlow nhigh oodr -- 


32 bi t store, nhigh is stored at addr; nlow is stored at addr+2. 


20 
oodr -- nlaw nhigh 


32 bit fetch, nhigh is fetched fran addr; nlow is fetched fran addr-2. 


2DUP 
n2 nl -- n2 nl n2 nl 


~ 
licates the top ~ 
values oo the stack. 
E'quivalent to OJER CNER. 


P,E,ID 


Oaed in the fonn called a colon-definition: 
: cccc 
••• 
; 


Creates a dictionary entry defining cccc as EqUivalent to the following sequence 
of Forth ,;,,ord definitions ' .•• ' until the next ' ; • or ' ;CDDE'. 
The curpiling 


process is done by the text interpreter as long as srATE is non-zero. 
Other 


details are that the <X>N1'EXT vocabulary is set to the CURRENI' vocabulary and that 
words with the precedence bit set (P) are executed rather than being canpiled. 


P,C,ID 


Terminate a oolon-definition and stop further ccrrpilation. 
Carpiles the run-tine 


is 
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:CODE 
P,C,UJ 


Used in the form: 
: cccc 
;OODE 


assembly rmem:mics 
Stop canpi 1ation and terminate a new defining w::,rd cccc by conpiling ( ;OO0E). 
Set 


the OJNrEX'l' vocabulary to ASSEMBLER, assembling to rrachine a::rle the following 
mnem::inics. 
This facility is incluierl for those users who may wish to write a Z80 


Assembler in FOR'fH. 


When cccc later executes in the form: 
cccc 
nnnn 
the ....ord nnnn will te created with its execution proce:::lure given by the machine 
ccrle following cccc. 
That is, when nnnn is execute:l, it does so by jrnping to the 
COOe after noon. 
An existing defining w::>rd must exist in cccc prior to ;OODE. 


;S 
P,ID 


Stop interpretation of a screen. 
;S is also the run-tirre v.0rd a:rt1piled at the errl 
of a colon-definition, which returns execution to the calling procedure. 


< 
nl 
n2 -- 
f 
ID 


Leave a true flag if nl i s less than n2; otherwise leave a false flag. 


[j) 


Setup for pictured nurreric output formatting using the w::,rds: 


<# 
# 
#S 
SIGN 
#> 
The conversion '.s done oo a double number prcducing text at PAD. 


(BUILDS 
C<ID 


usea. within a oolon-definition: 


: 
cccc 
<BUILDS 
•••• 


OOES> 
; 


Each ti..rre. cccc is executed, <BJit.00 defines a ~ 
word with a high level execution 


pro::edure. 
Executing cccc in the form: 
= 
nnnn 
uses <BUlLOS to create a dictionary entry for nnnn with a call to the OOES part 
for nnnn. 
When nnnn is later executed, it has the address of its pararreter area 
oo the stack and executes the words after COES> in o:cc. 
<BUILOO and IDES> allow 
run-tine procedures to be written in high level, rather than in assenbler caie (as 
required 1:1,- ;Cl)DE). 


nln2--f 
ID 


Leave a true flag if nl=n2 otherwise leave a false flag. 


nln2--f 
[j) 


Leave a true flag if n1 is greater than n2 otherwise leave a false flag. 
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c,w 


Reoove a number £ran the cx::DlpUtation stack and place as the nost accessible on the 
return stack. 
Use should be btlanced with R> in the sarre definition. 


w 


Print the value oontained at the a:ldress in free format, accordi ng to the current 
base. 


?COMP 


Issue error. rressage if oot a:npiling. 


?CSP 


Issue error message if stack p:,sition differs fran value saved in CSP. 


?ERROR 
f 
n -- 


Issue an error rressage numl::er n, if the toolean flag is true. 


?EXEC 


Issue an error rressage if not executing. 


?LOADING 


Issue an error rressage if not loading. 


?PAIRS 
nl 
n2 -- 


Issue an error rressage if nl does oot equal n2. 
The rcessage indicates that 


c:x:DPiled conditionals do not rratch. 


?STACK 


Issue an error rressage if the stack is out of l::ounds. 


?TERMINAL ' 
--- 
f 
. 


Perform a test of the terminal keyb:>ard for actuation of the break key. 
A true 


flag indicates actuation . 
• 


addr --- 
n 
w 


Leave the 16 bit contents of a1dress. 
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ABORT 
ID 


Clear the stacks and enter the execution state. 
Retuz;-n oontrol to the q;,erator' s 
terminal, printing a rressage appropriate to the installation. 


ABS 
n -- 
u 
ID 


Leave the absolute value of n as u. 


AGAIN 
crldr n -- 
( a:npiling l 
P,C2,W 


Userl in colon-definition in the form: 
BEX;IN 
••• 
!'GAIN 
At nm-time, AGAIN forces execution to return to oorres(X)nding B&;IN. 
The.re is oo 
effect co the stack. 
Execution cannot leave this loop (unless R> is executed one 


level below). 


At <XInpile time, !GAIN CXllpiles m.AN:::H with an offset fran HERE to a:ldr. 
n is 


used for CXI1pile-tirne error dlecking. 


ALLOT 
n -- 
ID 


Adi the signed ~ 
to the dictionary IXJinter IP. 
May te used. to reserve 


dictionary space or re-origin rremory. 
n is with regard to cx:nputer a:ldress type 
(byte or word). 


AND 
nl n2 -- 
n2 
ID 


Leave the bitwise logical "ANO" of nl and n2 as n3. 


B/BUF 
- 
n 


This constant leaves the number of bytes per disc b.lffer, the byte count read fran 
disc l'1,' BLOCK. 


B/SCR 
- 
n 


This cx:mponent leaves the numl:er of blocks per editing screen. 
By convention, an 
Erliting screen is 512 bytes, organised as 8 lines of 64 characters each. 


BACK 


calculate the backward branch offset fran HERE to a:ldr and oarpile into the next 
available dictionary rremory a:l.dress. 


BASE 
- 
a:ldr 


A user variable cxmtaining the current nunber base used for input and ootput 
cx,nversion. 
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BEGIN 
-- 
addr n 
C cmpilation) 
P,ID 


Occurs in a oolon-definition in the form: 
BffiIN 
• • • 
WTIL 
BOOIN 
..• 
l'GAIN 
BffiIN 
• • • 
iliILE 
• • • 
REPEAT 


At run-time, !EiIN narks the start of a sequence that nay be repetetively 
executed. 
It serves as a return point £ran the oorresponding lNI'IL, IGAIN or 
REPEAT. 
When executing t.Nl'IL, a return to IE:iIN will occur if the top of the 


stack is false; for !GAIN and REFF.AT, a return to JE:iIN always occurs. 


A cx:rrpile time EB;IN leaves its return cddress and n for oanpiler error checking. 


BL 
-- 
C 


A oonstant that leaves the ASCII value for blank. 


BLANKS 
addr a:>unt - 


Fill in an area of rre:oory l:eginning at addr with blanks. 


BLK 
-- 
addr 
ID 


A user variable oontaining the block number t:eing interpreted. If zero, input is 
being taken fran the terminal input ruff er. 


BLOCK 
n -- 
addr 
ID 


Leave the rrem::>ry a:idress of the block b.Jffer oontaining block n. 
If the block is 


not already in rrerrory, it is transferred fran disc to whichever l:::uffer was least 
r ecently written. If the block occupying that l::uffer has been markai as updated, 
it is re-written to disc before block n is read into the bJffer. see also 11.JFFm, 
R/W UPDATE FL!EH. 


BRANCH 
C2,W 


The run-time procedure for unconditionally branch. 
An in-line offset i s aided to 


the interpretive pointer IP to branch ahead or back. 
llWCH i s carpiled by ELSE, 
1'GAIN, REPEAT. 


BUFFER 
n -- 
addr 


Obtain the next rrerrory bJ.ffer, assigning it to block n. 
If the contents of the 


bJffer are narke:l up as updated., it is written to the disc. 
The block is not read 


fran the disc. 
The a1dress left is the first cell within the b.Jffer for data 


storage . 


Cl 
b addr -- 


Store 8 bits at a1dress. 
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c. 
b -- 


Store 8 bits of b into the next available dictionary byte, advancing the 
dictionary I;X>inter. 


C@ 
addr --- 
b 


Leave the 8 bit contents of rrenory a:ldress. 


CASE 
--- n (ccrnpiling) 


Ocx:urs in a oolon definition in the form: 


CASE 
n OF •••• • ENlXJF 


ENOCASE 
At run-tirre, CASE rmrks the start of a sequence of OF ••• ENOOF statarents. 


At ccrnpile ti~ CASE leaves n for COTipiler error checking. 


CFA 
pfa -- 
cfa 


Coovert the pararreter field address of a definition to its code field address. 


CMOVE 
fran to count -- 


Move the specified quantity of bytes beginning at a:idress '£ran' to a:ldress 
I to'. 
The oontents of address 'fran' are rroverl first procee::ling towards high rrarory. 


COLD 


The oold start procedure to crljust the dictionary pointer to the minimum standard 
and restart via AOORT. 
May l:e called. fran the terminal to reoove application 


pr03rams and restart. 


COMPILE 
C2 


When the v0rd cx:mtaining a::MPILE executes, the execution address of the v0rd 
following CXMPILE is oopied (ccrnpiled) into the dictionary. 
This allCMS specific 
canpilation situations to re handled in oodition to sinply ccrrpiling an execution 
address (which the interpreter already does>. 


CONSTANT 


A defining w:>rd used in the form: 


n 
CXJNSTANI' 
cccc 


w 


to create word cccc, with its parameter field oontaining n. 
When cccc is later 
executed, i t will push the value of n cnto the stack. 


CONTEXT 
- 
addr 
u,w 


A user variable oontaining a pointer to the \OCabulary within which dictionary 
searches will first begin. 
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COUNT 
a1drl - 
a1dr2 
ID 


~ve the byte aidress aidr2 and byte oount n of a rressage text beginning at 
address c:ddrl. , It is presuned that the first byte at crld.rl contains the text byte 
count and that the actual text starts with the secorxl byte. 
typically, CXXJNI' is 


followed by 'IYPE. 


CR 
ID 


Transmit a carriage return and line feed to the selected output device. 


CREATE 


A defining 1«>rd userl in the form: 
CREATE= 


by such 1«>rds as OODE and OONSTANI' to create a dictionary heciier for a Forth 
definition. 
The cxxle field oontains the a:idress of the w.:>rd' s pararreter field. 
A 


new \liOrd is created in the ClJRRENT vocabulary. 


CSP 
--- 
a1dr 
u 


A user variable tenporarily storing the stack pointer p:>5ition, for cx:npilation 
error checking.- 


D+ 
dl d2 -- 
dsum 


Leave the OOuble number sum of two double numbers. 


D+· 
dln-d2 


AA>ly the sign of n to the double m.1nber dl, leaving it as d2. 


D. 
d -- 
LI 


Print a signed double mnnber £ran a 32 bit O..O's cx:nplanent value. 
The high-order 


16 bits are nost accessible a,, the stack. 
Conversion is perfonned according to 


the current l:ase. A blank fo:UCMS. 
Pronounced D-dot. 


D.R 
d 
n --- 
IX) 


Print a signe:l double number d right, aligned in a field n characters wide. 


DABS 
d --- 
oo 


Leave the absolute value of a double number. 


DECIMAL 
ID 


Set the m.ureric oonversion BASE for decimal input-output. 
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DEFINITIONS 
LI 


Used in the form: = DEFINITIONS 
Set the OJRRENT vocabulary to the CXNl'EXT wcabulary. 
In the exarrple, executing 
vocabJlary narre cccc made it in the oontext vocabulary, and executing IEFINITIONS 
made t:oth specify vocabulary =· 


DIGIT 
C 
nl -- 
n2 tf 
(ok) 


C 
nl -- 
ff 
(bad) 


Cawerts the ASCII characters c (using base nl) to its bi nary e::JUival ent n2, 
acccmpanied by a true flag . 
If the oonversion is invalid, l eaves only a false 


flag. 


· DLITERAL 
d -- 
d 
(executing) 


d -- 
(~ilingl 
p 


If cx:rrpiling, ccmpile a stack double number into a literal. Later execution of 
the definition oontaining the literal will push it to the stack. If executing, 
the number will remain oo the stack. 


DMINUS 
dl -- 
d2 


Coovert dl to its double number two's canplement. 


DO 
nl 
n2 -- 
(execute) 


addr n -- 
(cx:mpile> 


Occurs in a oolon-defini tion in the form: 
IXl 
••• 
IOOP 
IXl 
• • • 
+IOOP 


P,C2,IJJ 


At run time, 00 t::Egins a sequence with repetetive execution oontrolled by a loc,p 
limit nl and an index with initial value n2. 
00 rerroves these fran the stack. 


O(xxl reaching IOOP the index is incremented by one. 
Until the new index equals or 


exceeds the limit, execution loops back to just after ro otherwise the lcx:,p 
parameters are discarded and execution oontinues ahead. 
Both nl and n2 are 
detennined at run-time and may be the result of other cperations. 
Within a loc,p, 


'I' will CXJpy the current value of the index to the stack. 
see I, IOOP, +IOOP, 


IBAVE. 


When cx:rrpiling within the oolon-definition, 00 cx:rrpiles (00), leaving the 
following a:idress a:l.dr and n for later error checking. 


DOES) 
w 


A 1'110rd which defines the run-time action within a high level defining ~rd. 
OOES> 
alters the cx:de field and first pararreter of the neM word, to execute the sequence 
of cmpiled ~rd addresses following OOFS>. 
Used in cnnbination with W!Ll:Ei>. 


When the word OOES> part executes, it begins with the a:l.dress of the first 
pa.rareter of the new- word oo the stack. This allCMS interpretation using this 
area or its oontents. 
Typical uses incli.rle the Forth assenbler, ncl.ti-d.i.rre.nsional 


arrays and a:mpiler generation. 
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DP 
U,L 


A user variable, the dictionary pJinter, which contains the address of the next 
free rrerory above the dictionary. 
The value may l:e read by HERE and altered by 
ALim. 


DPL 
-- 
aldr 
U,10 


A user variable oontaining the m.unber of digits to the right of the decimtl oo 
double integer input. It may also t:e usEd to OOld output oolrnn location of a 
decimal point, in user generate::1. formatting. 
The default value on single number 


input is -1. 


DROP 
n -- 
10 


Drop the number fran the stack. 


DUMP 
10 


Print the aontent.s of n m:rrory locations beginning at a:ldr. 
Both crldresses and 


contents are shown in the current nurreric l:a.se. 


DUP 
n---nn 


Oq;>licate the value oo the stack. 


ELSE 
aldrl nl - 
addr2 n2 
( carpiling) 


Occurs within a colon~efinition within the form: 
IF 
• • • 
ELSE 
• • • 
ENDIF 


10 


P,C2,10 


At run-time, ELSE executes after the true part following IF. 
EL.SE forces the 


execution to skip OV"er the following false part, and resurres execution after the 
IINDIF. 
It has oo stack effect. 


A carpile t~ ELSE anplaces branch reserving a branch offset, leaves the address 
addr2 and n2 for error treating. 
ELSE also resolves the pending forward branch 


fran IF by calculating the offset fran addrl to HERE and storing at addrl. 


EMIT 
C -- 
10 


Transmit ASCII character c to the selected output device. 
our is incra:nente:i for 


each character output. 


EMPTY-BUFFERS 
ID 


Make all block-bJffers as arpty, not necessarily affecting the contents. 
Upiate:i 


blocks are not written to the disc. 
This is also an initialization procedure 


before first use of the disc. 
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ENCLOSE 
addrl 
C -- 
addr 1 nl n2 
n3 


The text scanning primitive used by W)RD. 
Fran the text a'.ldress addrl and an 
ASCII delimiting character c, is determined the byte offset to the first 
non~elimiter character nl, the offset to the first delimiter after the text n2, 
and the offset to the first character not inclu::le:3.. 
This prcx:e:lure will not 
process past an ASCII 
I null', treating it as an unconditional delimiter. 


END 
P,C2,I.O 


This is an 'alias' or duplicate definition for lNI'IL. 


ENDCASE 
addr n - 
Ccx:rnpilel 


occurs in a colon definition in the form: 
CASE 
n OF ••••• ENOOF 


ENOCASE 
At run-time ENOCASE marks the oonclusion of a CASE statenent. 


At cx:rnpile time ENCCASE canputes forward branch offsets. 


ENDIF 
addr 
n -- 
(cx:rnpilel 
P,00,I.O 


At run-time, ENDIF serves only as the destination of a forward branch £ran IF or 
Er.SE. 
It marks the oonclusion of the conditional structure. 
'lHEN is another nane 
for ENDIF. 
Both names are supported in Fig-roRTH. 
See also IF and ELSE. 


At cx:rnpiletime:, ENDIF a:nputes the forward branch offset £ran a:idr to HERE and 
stores it at oodr. 
n is used for error tests. 


ENDOF 
addr 
n 
- 
(CCJipilel 


Used as ENDIF b.Jt in CASE statements. 


ERASE 
addr 
n -- 


Clear a reg ion of rrerrory £ran zero to addr over n a:1.dresses. 


ERROR 
line --- 
in blk 


Execute error ootification and restart of system. 
WARNnli is first examined. 
If 


1, the test of line n, relati ve to screen 4 and drive O is printed. This line 
number rray be fX)Sitive or negative, and beyond just screen 4. 
If WARNIN:;--0, n is 
just printed as a rressage number Coon disc installation). 
If warning is -1, the 
definition ABJRT is executed, \llhich executes the system AOORT. 
The user may 


cautiously m:xlify this by altering CABJRT). 
Fig-FORTH saves the contents of in 
and BU< t.o assist in determining the location of the error. 
Final action is 
execution of QUIT. 
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EXECUTE 


Execut.e the definition whose cx:xle field address is on the stack. 
The rode field 
address is also called the a:mpilation address. 


EXPECT 
addr oount - 
ID 


Transfer dlaracters fran the terminal to address, until a return or the count of 
characters has teen received. 
One or rrore nulls are a:ided at the erd of the 
text. 


FENCE 
- 
addr 
u 


A user variable oontaining an a:1.dress, below which FORGEI'ting is traPl.)ed. 
To 


forget t:elow this r;:oint, the user must alter the contents of the FEN:E. 


FILL 
addr quan b -- 


Fill rrerory at the address with the specifierl quantity of bytes b. 


FIRST 
--- 
n 


A constant that leaves the address of the first {lowest) block b.Jffer. 


FLD 
- 
addr 
u 


A user variable for control of number ootput field width. 
Presently unused in 


Pig-EDRTH. 


FORGET 
E,ID 


Deletes definition named cccc £ran the dictionary with all entries [X'lysically 
following it. 
In Fig- FORTH, an error nessage will cx:cur if the CURRENT and 


OJNIBXT vocal::ularies are not currently the sarre. 


FORTH 
P, LI 


The narre of the prirrary ,x,cabulary. 
Execution makes FOR'IH the a>NI'EXT vcx:abulary. 


until additional user vocabularies are defined, new user de finitions becone a part 
of 'FOR'IH. 
FORTH i s imnediate, so it will execute during the creation of a 


colon-definition, to select this rocabulary at carpile tine. 


HERE 
-- 
addr 
ID 


Leave the addres s of the next available dictionary locat ion. 


HEX 
w 


Set the nurreric conversion base to sixteen (hexadeci.Ral) . 
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HLD 
-- 
addr 
ID 


A user variable that OOlds the a:l.dress of the latest character of text during 
nurreric output conversion. 


HOLD 
C -- 
ID 


Used be~ <# and #> to insert an ASCII character into a pictured nurreric output 
string. 


e.g. 
2E IDLD will place a decimal point. 


-- 
n 
C,ID 


Used within a CO-IOOP to cx:,py the loc,p index to the stack. 
Other use is 
imple:nentation dependent. 
see R. 


ID. 
a:l.dr -- 


Print a definition's name fran its narre field 00.dress. 


IF 
f -- 
(run-time) 
a:l.dr 
n 
CCUll>ile) 
P,C2,ID 


Oo::urs in a oolon-definition in the fonn: 
IF 
(tp) 
• • • 
ENDIF 
IF 
Ctpl 
.. • 
El'.SE 
Cfpl 
ENDIF 
At run-tine, IF selects execution tased on a txx>lean flag. 
If f is a true 
Coon-zero}, execution oontinues ahe.:rl throl.lg'h the true pa.rt. 
If f is false 
C zero), execution skips till just after ELSE to execute the false part. 
After 
either part, execution resurres after ENDIF. 
EI.SE and its false part are optional; 
if missing, false execution skips to just after ENOIF. 


At canpile ti.Jre, IF canpiles OBRAOCH and reserves space for an offset at cddr. 
addr and n are used later for resolution of the offset and error testing. 


IMMEDIATE 


Mark the rrost recently rrade definition so that when encountere:i at cx:rrpile t.i.ne it 
will te executed rather than cx:rrpiled, i. e. the precedence bit in its header is 
set-. 
This nethod allows definitions to handle unusual cx:rrpiling situations, 


rather than b.Jild then into the fundan'ental cx:rrpiler. 
'l11e user may force 
CXJTpilation of an inrnediate definition ~ precerling it with (CCMPILE). 


IN 
-- 
a:l.dr 
ID 


A user variable oontaining the ~ 
offset within the current input text bJ.ffer 


(tenninal or disc) fan which the next text will be accepted. 
W)RD uses and rcoves 


the value of IN. 
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INDEX 
fran to - 


Print the first line of each screen over the range fran, to. 
This is use:l to view 


the CXlTll'ellt lines of an area of text oo disc screens . 


INTERPRET 


The outer text interpreter, which sequential ly executes or cx:mpiles text fran the 
input stream (terminal or disc) depending on srA'lE. 
If the word name cannot l::e 


fourxi after a search of CI)N'l'EXT and then aJRRENl', it is converted to a number 
according to the current base. 
That also failing, an error rressage echoing the 
name with a "7" will re given. Text input will l::e taken according to the 
convention for W)RI). 
If a decimal point is found as part of a num1::er, a double 


numl::er value will t:e left. 
The decimal point has no other p.irpose than to force 


this action. 
See mMBER. 


KEY 
- 
cc 
ID 


Leave the ASCII value of the next terminal key struck. 


LATEST 
-- 
addr 


Leave the nane field address of the topoost w::>rd in the current vocabulary. 


LEAVE 
c , ID 


Farce termination of a ID-IOOP at the next cpportunity cy7 setting the L:x,p limit 
equal to the current value of the index. 
The index itself remains unchanged, and 


execution prcx:eeds oormally until IOOP or +IOOP i s encountered. 


LFA 
pfa -- 
lfa 


Calvert the parameter field a:idress of a dictionary definition to its link field 
a&iress. 


LIMIT 
- 
n 


A oonstant leaving the address just above the highest rreoory available for a disc 
b.tffer. 
Usually, this is the highest system rreoory. 


LINE 
n --- 
irldr 


Leave a:ldress of line n of current screen. 
This address will re in the disc 


b.tffer area. 


LIST 
n --- 
ID 


Display the ASCII text of screen n on the selected output device. 
s:::R contains 


the screen nunber during and after this precess. 
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LIT 
--- 
n 
C,LO 


Within a oolon-definition, LIT is aut.anatically cxrnpiled before each 16 bit 
literal number encountered in input text. later execution of LIT causes the 
contents of the next dictionary a:ldress to be pJ.shed to the stack. 


LITERAL 
n -- 
(cx:mpiling) 
P,C2,ID 


If canpiling, then cxrnpile the stack value n as a 16 bit literal. This definition 
is inmed.iate so that it will execute during a oolon-definition. 
The intende:l use 
is: 


: 
xxx 
(calculate ) 
LITERAL 
: 
Canpilation is suspende:i for the canpile time calculation of a value. Carpilation 
is resurre.;1 and LITERAL a::mpiles this value. 


LOAD 
n -- 
LO 


.Be:Jin interpretation of screen n. 
Loading will terminate at the end of the screen 
or at ;S. 
See ;S and -->. 


LOOP 
a:ldr n --- 
( canpiling I 
P,C2,LO 


oo::urs in a colon-definition in the form: 
ID 
••• 
WOP 
At run-tine, LOOP selectively oontrols branching back to the corresponding ro 
based oo the loop index and limit. 
The loop index is incremented by one and 
carpared to the limit. 
The branch back to 00 occurs until the index a:;ruals or 
exceeds the limit; at that time, the pararreters are discarded and execution 
continues ahead. 


At cx:rrpile tine, LOOP canpiles (IOOP) and uses 00.dr to calculate an offset to CO. 
n is used for error testing. 


nl n2-d 


A mixed rragnitu1e rcath cperation which leaves the OOuble number signe:1 prcrluct of 
b«> signe::1 numbers. 


Mi 
dnl--n2n3 


A mixed magnitu1e rcath q,erator which leaves the signe:1 remainder n2 and signe:1 
quotient n3, fran a double number dividend and divisor nl. 
The remainder takes 
its sign fran the dividend. 


M/ MOD 
uil u2 
- 
u3 
u'l4 


An unsigne:1 mixe:1 magni tu1e rcath q,eration which leaves a double quotient \.114 and 
remainder u3, £ran a double dividend u::ll and single divisor u2. 


MAX 
nl n2 -- 
rrex 
LO 


Leaves the greater of two numbers. 
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MESSAGE 
n - 


Print oo the selected oo.tput device the text of line n relative to screen 4 of 
drive 0. 
n may ·te p:,sitive or negative. 
MESSAGE may be used to print incidental 
text such as report headers. If ~ 
is zero, the rressage will sinply l::e 


printed as a nurrber (disc mavailable). 


MIN 
nl n2 - 
rnin 
w 


Leave the smaller of - 
numbers. 


MINUS 
nl - 
n2 
w 


Leave the two's cx:rrplerrent of a number. 


MOD 
nl n2 -- 
nod 
w 


Leave the remainder of nl/n2, with the sarre sign as nl. 


NEXT 


This is the inner interpreter that uses the interpretive IP to execute ccrrpiled 
Forth definit ions. It is oot directly executed tut is the return point for all 
oode procedures. It acts by fetching the a:ldress pointed by IP, and storing this 
value in register W. 
It then jrnps to the address p:>inted to by the address 


pointed to by w. 
W points to the cxxle field of a definition which oontains the 


address of the cxxle which executes for that definition. 
This usage of indirect 


threaded. code is a rrajor contributor to the p:,wer, 
p:,rtability and extensibility 


of Forth. 


NFA 
pfa -- 
nfa 


Calvert the paraneter field address of a definition t.o its narre field. See PFA. 


NUMBER 
addr - 
d 


COOvert a dlaracter string left at aidr with a preceeding count, t.o a signerl 
double number, using the current nurreric base. 
If a decimal p;::,int is encountere::l 


in the text, its position will re given in IPL, l:::ut oo other effect occurs. 
If 


nurreric oonversion is oot pJSsible, an error rressage will be given. 


OFFSET• 
-- 
addr 
u 


A user variable which nay oontain a bl ock offset to disc drives. 
The oontents of 
OFFSET is adde::i to the stack number by B!OCK. 
Messages by MESSAGE are independent 


of OFFSET. 
See BIOCK, rno, CRl, MESSAGE. 


OR 
nl n2 -- 
or 
w 


Leave the bit-wise logical "CR" of t:wo 16 bit values. 
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OUT 
-- 
a:ldr 
u 


A user variable that oontains a value incrarented bi' EMIT. The user may alter and 
examine cur to oontrol display fonnatting. 


OVER 
nl n2 -- 
nl n2 nl 
ID 


Copy the secorxl stack value, placing it as the new top. 


PAD 
a:ldr 
ID 


Leave the a:ldress of the text output b.Iffer, which is a fixed offset above HERE. 


PFA 
nfa -- 
pfa 


Calvert the nane field address of a cxxrpiled definition to its pararreter field 
address. 


POP 


Tte ccrle sequence to rem:>ve a stack value and return to NEXT. OOP is oot directly 
executable, b.lt is a Forth re-entry point after machine cede. 


PREV 


A variable oont.aining the address of the disc t:x.tffer rrost recently referenced. 
The lPD!\TE cnnnand narks this b.Jffer to be later written to disc. 


PUSH 


This code sequence pushes machine registers to the ccrrputation stack and returns 
to NEXT. 
It is not directly executable, b.It is a Forth re-entry point after 


machine oxle. 


PUT 


'Ibis code sequence stores na.chine register contents CNer the topnost ccrrputation 
value and returns to ?-EXT. 
It is not directly executable, tut is a Forth re-entry 


point after nachine cxxie. 


QUERY 


Iqrut 80 characters of text (or until a "return") fran the operator's terminal. 
Text is positioned at the address contained in TIB with IN set to zero. 


QUIT 
LI 


Clear the return stack, stop catpilation and return oontrol to the cperator' s 
texminal. 
No message is given. 
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r 


" 
- 
n 
u 


A user variable ~ich may contain the location of an Editing cursor, or other file 
related function. 


Rf 
- 
addr 
u 


A user variable Wich nay contain the location of an editing cursor, or other file 
related function. 


R/ W 
addr bllc 
- 


The Fig-Forth standard read-write l inkage. 
OOdr specifies the source or 


destination block l:uffer. 
blk is the sequential number of the referenced block; 


and f is a flag for f-0 write and f-1 read. 
R/W detennines the location oo mass 


storage, performs the read-write and any error dtecking. 


R> 
- 
n 
w 


Reoove the top value £ran the return stack and l eave it oo. the carputation stack. 
See >Rand R. 


RO 
-- 
addr 
u 


A user variable containing the initial location of the return stack. 
Pronounced 


R-zero. 
See RP! 


REPEAT 
addr n -- 
C oanpiling l 
P,C2 


Used wi. thin a rolon-def ini tion in the foon: 
Ba;IN 
• • • 
~lILE 
• • • 
REPFAT 


At run-time, REPEA.T forces an unconditional branch back to just after the 
corresponding m;rn. 


At oanpile tilre, REPFAT oanpiles m=i and the offset fran HERE to oodr. 
n is 
used for error testing. 


ROT 
nl n2 
n3 -- 
n2 
n3 nl 
w 


Rotate the top three values oo the stack, bringing the third to the top • 


..iar 


Leaves the current value in the return stack pointer register. 


RPI 


A cx::rnputer dependent procedure to initialise the return stack pointer fran user 
variable RO. 


S-->D 
n --- 
d 


Sign extend a single number to form a OOuble number. 
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so 
-- 
addr 
u 


A user variable that cx:mtains the initial value for the stack pointer pronounce:l 
S-zero. 
See SP ! 


SCR 
oodr 
u 


A user variable oontaining the screen number roost recently referenced cy' LIST. 


SIGN 
nd---d 
ID 


Stores an ASC:II "-" sign just l:efore a oonverted nurreric output string in the 
text output b.lffer when n is negative. 
n is discarded, blt double number d is 
maintained. 
Must te used bet~ <# and #>. 


SMUDGE 


Used during "-Ord definition to toggle the 11smxlge bit" in a definition's narre 
field. 
This prevents an uncanpleted definition fran being lowld during dictionary 
searches, until o::Jllpiling is .a:rnpleted without error. 


SP I 


A canputer dependent proc."edure to initialise the stack i;:ointer fran SO. 


SPO 
-- oodr 


A CXInpUtor dependent prcx:e:lure to return the address of the stack i;x:,sition to the 
top of the stack, as it was be:fore SP@ was executed. (e.g. 1 2 SP@ @ ••• would 
print 2 2 1). 
· 


SPACE 


Transnit an AS::II blank to the output device. 


SPACES 
n -- 
ID 


Transmit n ASCII blanks t.o the ootput device. 


STATE 
- 
oodr 
ID, U 


A user vari able oontaining the cxmpilation state. A non-zero indicates 
a:rrpi l ation. 
The value itsel f may be .inpl enentation dependent. 


SWAP 
nl n2 -- n2 nl 
ID 


Exchange the top - 
values en the stack. 
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TASK 


A no-operation ~ 
..tlich can nark the boundary bebieen applications. 
By 
forgetting TASK and re-a::mpiling, an applicaton can be discarded in its entirety. 


TEXT 
C 
- 


Aa:ept the following test to PAD. 
c is the text delimiter. 


THEN 
P,a:>,ID 


An alias for END IF. 


TIB 
u 


A user variable oontaining the addresses of the terminal input blffer. 


TOGGLE 
!>'.ldrb- 


CCnplarent the contents of 1"ldr by the bit pattern b. 


TRAVERSE 
!>'.ldrl n -- a:ldr2 


Move across the narre field of a Fig-FOEmI variable length nane field. 
a:ldrl is 


the address of either the lenJth byte or the last letter. 
If n=-1, the rotion is 
toward low rrerory. 
The addr2 resulting is the crldress of the other end of the 
name. 


TYPE 
addr oount - 
w 


Transmit oount characters £ran a:1dr to the selected ootput device. 


U< 
ulu2-f 


Leave the b:x>lean value of an' unsigned less-than cxuparison. 
Leaves f=l for ul > 


u2; otherwise leaves O. 
Thi$ function should be used when cx:mparing rrerory 
addresses. 


ul u2 -- u1 


Leave the unsigned double number prcrluct of bo1o unsigned number s. 


u. 
u -- 


Prints an unsigned 16 bit number oonverte:l according to 131\.SE. A trailing blank 
follows. 
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U/ 
ud ul -- u2 u3 


La:lve the unsigned ranainder u2 and unsigned quotient u3 fran the unsigned double 
dividend u::1 and unsigned divisor ul. 


UNTIL 
f - 
(run-tine) 
addr n -- 
< =npile J 


Oo::urs within a oolon-definition in the form: 
8&,IN , , , lNI'IL 


P,C2,W 


At run-tine, l.Nl'IL oontrols the ronditional branch back to the corresponding 
IEGIN. 
If f is false, execution returns to just after EE;IN, if true, execution 


continues ahead, 


At canpile-tiIIe, t.NI'IL conpiles (OERAOCH) and an offset fran HERE to a:ldr. 
n is 
used for error tests. 


UPDATE 
U) 


Marks the rrost recently referenced block (pointed to by PREVJ as altered. 
The 


block will subsequently te transferred to disc should it's b.iffer be required for 
storage of a di fferent block. 


USE 
- 
oo.dr 


A variable rontaining the a::ldress of the block b.lffer to use next, as the least 
recently written. 


USER 
n -- 
U) 


A defining ~rd used in the form: 
n usm cccc 
....tlich creates a user variable cccc. 
The parameter field of cccc oontains n as a 
fixed offset relative to the user pointer register UP for this upper variable. 
When cccc is later executed , it places the sum of it' s offset and the user base 
ad:lress en the stack, as the storage M.dress of that particular variable. 


VARIABLE 
E,W 


A defining -word used in the form: 
n VARIABIE cccc 


When VARIABIB is executed, it creates the definition cccc with its paraneter field 
initialise:i to n. 
wten cccc is later executed, the a:ldress of its parameter field 
(oontaining n) is left oo the stack, so that a fetch or store may access this 
location. 


VDC-LINK 
oo.dr 
u 


A user variable oontaining the address of a field in the definition of the m:,st 
recently created wcab.tlary. 
All vocabulary names are link.Erl by these fields, to 


allow oontrol for FORGEI'ting through nrultiple vocabularies. 
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VOCABULARY 
E,L 


A defining -w:>rd used in the fonn: 


=mu\RY = 
to create a vocabulary definition cccc. 
Subsequent use of cccc will make it the 
OONl'EXT vocab.J.lary which is searche:l first by INTERPRET. 
The se::iuence "c:x,cc 


[EFilUTIONS" will also make occc the CURRENI' vocabulary, into which, new 
definitions are placed. 


I n Fig-FOR'm, cccc will also be chained so as to inclu:ie all definitions of the 
vocabulary in \ltlich cccc is itself defined. All vocabularies ultimately chain to 
Forth. 
By convention, vocabulary names are to re declared JM!EDIATE. see 


\<JC-LINK. 


VLIST 


List the names of the definitions in the context vocabulary. 
Pressing •Break• 


will tenninate the listing. 


WARNING 
- 
addr 
u 


A user variable, containing a value oontrolling rressages. 
I f = 1 disc is present, and screen 4 of drive O is the base location for rressages. 
I f= 0, oo disc is present and rressages will te presented by number. If= -1, 
execute (AIDRT) 
for a user specified procedure. 
see MESSl!GE, ERRCR, AEORT. 


WHERE 
nl n2 -- 


If an error occurs during IDAD £ran disc, mROR leaves these values on the stack 
to shOwrf the user where the error occurred. WHERE uses these to print the screen 
and line number of where this is. 


WHILE 
f -- Crun-tirnel 
a1drl nl -- a1drl nl a:ldr2 n2 
P,C2 


Occurs in a oolon-definition in the form: 
JB;IN ••• if!ILE (tpl ••• REPFAT 


At run-time, WHILE selects oonditiona.l execution tased on b:x>lean flag f. 
If f is 
true (oon-zero), ~ILE oontinues execution of the true part through to REPEAT, 
which then branches back to ea::;m. 
If f is false (zero), execution skips to j ust 


after REPFAT, exiting the structure. 


At canpile time, WHILE anplaces (Om.ruoi) and l eaves addr2 of the reserved offset. 
The stack values will re resolved t1f REPFAT. 


WIDTH 
--- addr 
u 


In Fig-FORTH, a user variable containing- the rraximl..11\ number of letters save:] in 
the cx:n,pilation of a definitions name. 
It must be 1 through to 31, having a 


default value of 31. 
The name character count and its natural characters are 


save:l, q:, to the value of wrom. 
Ttl! value ma.y 1::e change:] at any tirne within tfie 
alxlve limits. 
. 
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WORD 
c- 
ID 


Read the next text characters fran the input stream t:eing interpreted, until a 
delimiter c is found, storing the packed character string t:egiMing at the 
dictionary blffer HERE. vORO leaves the character count in the first l::¥te, the 
characters, and ends with OKJ or rrore blanks. 
Leading o:curances of c are 
ignored. 
If BLK is zero, text is taken fran the terminal input b.Jffer, otherwise 
£ran the disc block stored in BIB. 
See BU< , IN. 


X 


This is pseudonym for the 11null" or dictionary entry for a name of ooe character 
of AS:II null. It is the execution procedure to terminate interpretation of a 
line of text £ran the tenninal or within a disc bJffer, as toth bJffers always 
have a null at the end. 


XOR 
nl n2 -- xor 
LI 


Leeve the bi t-wise lcqical Exclusive-CR of M> values. 


C 
P,LI 


Used in a colon-definition in the form: 


: xxx 
l«>rds 
nore ; 
Susperrl cx:mpilation. 
The \oOrds after 
are executed, oot a:mpiled. 
Th.is allows 
calculation or a:mpilation exceptions before resuming cxrrpilation with 
• 
See 
LITrnAL, 


~OMPIL~ 
P,C 


Used in a oolon-def ini tion in the form: 
; XXX 
<XMPILE 
fORTH· ; 
cx:MPILE will force the cx:mpilation of an imnediate definition, that would 
otherwise execute during ca1lJilation. 'Itie above exanple will select the FORIB 
vocab.tl.ary when xxx executes, rather than at oorpile time. 


J 


LI 


Resurre cx:npilation, t.o the oorpletion of a oolon-definition. see 


ADDITIONAL GLOSSARY 


C/ L 
-n 


A o:xistant oontaining the number of characters per line ( 64). 


WARM 


This will perfonn a warm-start. 
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' 


I 


NOOP 


This will perform a oo-q>eration, i.e. do nothing. 


WI\RMpCOLD 


This allows you to preserve any R)R'l'H w:>rd define:} to date, so that a OOLD start 
will oot delete them. 
When saving your cxxie, save fran 24832 to HERE. 


e.g. 
: NEH'l)RD • " 'IBIS WILL IE PRESERVED FJi. WARM-XDLD " ; 


If we now do a roLO start this will be lost, b..tt if we first key in WARM->roLD arrl 
then do a OOLD start, it will still be there. 
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IDEAL GLOSSARY 


WORD 
PARAMETERS 
ACTION 


WCRV 
fti'f, LEN, OJL, 
scroll the window vertically with wrap by 
RCM, NPX 
NPX pixels. 


SCRV 
filr, LEN, OJL, 
Scroll the window vertically without 
RCM, NPX 
wrap by NPX pixels. 


WRR1V 
!Gr, LEN, COL, 
Scroll the window 1 pixel right with wrap. 
Ra-I 


WRL1V 
!Gr, IEN, <DL, 
Scroll the window 1 pixel left with wrap. 
Ra-I 


WRR4V 
!Gr, IEN, rot, 
Scroll the windc:M 4 pixels right with wrap. 


Ra-I 


WRL4V 
!Gr, LEN, CDL, 
Scroll the window 4 pixels left with wrap. 
Ra-I 


WRR8V 
!Gr, LEN, OJL, 
Scroll the window 8 pixels right with wrap. 
Ra-I 


WRL8V 
!Gr, LEN, CllL, 
Scroll the winda,,/ 8 pixels left with wrap. 
Ra-I 


SCR1V 
!Gr, LEN, CllL, 
Scroll the windcM 1 pixel right without 
Ra-I 
wrap. 


SCLW 
!Gr, I.EN, CDL, 
Scroll the window 1 pixel left wi t.hout 
Ra-I 
wrap. 


SCR4V 
!Gr, LEN, OOL, 
Scroll the window 4 pixels right without 
Ra-I 
wrap. 


SCL4V 
!Gr, IBN, CllL, 
Scroll the window 4 pixels left without 


Ra-I 
wrap. 


SCR8V 
!Gr, !EN, CDL, 
Scroll the window 8 pixels right without 


Ra-I 
wrap. 


SCL8V 
!Gr, LEN, CllL, 
Scroll the wind<::M 8 pixels left without 
Ra-I 
wrap. 


ATTRV 
!Gr, LEN, CllL, 
Scroll the winck:M attributes 1 character 


Ra-I 
right with wrap. 


ATTLV 
!Gr, LEN, OJL, 
Scroll the window attributes 1 character 
Ra-I 
left with wrap. 


ATTUPV 
!Gr, LEN, CllL, 
Scroll the window attributes 1 character 
Ra-I 
up with wrap. 


ATTDNV 
!Gr, LEN, CllL, 
Scroll the window attributes 1 character 
Ra-I 
down with wrap. 


WCRM 
SPN 
Scroll the Sprite vertically with wrap by 
NPX pixels. 


119 


SCAM 
SPN 
Scroll the Sprite vertically without wrap 
by NPX pixels. 


WRR1M 
SPN 
Scroll the Sprite 1 pixel right with wrap. 


WRL1M 
SPN 
Scroll the Sprite 1 pixel left with wrap. 


WRR4M 
SPN 
Scroll the Sprite 4 pixels right with wrap. 


WRUM 
SPN 
Scroll the Sprite 4 pixels left with wrap. 


WRRSM 
SPN 
Scroll the Sprite 8 pixels right with wrap. 


WRLSM 
SPN 
Scroll the Sprite 8 pixels left with wrap. 


SCRIM 
SPN 
Scroll the Sprite 1 pixel right without wrap. 


SCUM 
SPN 
Scroll the Sprite l pixel left without wrap. 


SCR,M 
SPN 
Scroll the Sprite 4 pixels right without 
wrap. 


SCUM 
SPN 
Scroll the Sprite 4 pixels left without wrap. 


SCRSM 
SPN 
Scroll the Sprite 8 pixels right without 
wrap. 


SCLSM 
SPN 
Scroll the Sprite 8 pixels left without wrap. 


ATTRM 
SPN 
Scroll the Sprite attributes 1 character 
right with wrap. 


ATTLM 
SPN 
Scroll the Sprite attributes 1 character 
left with wrap. 


ATTUPM 
SPN 
Scroll the Sprite attributes 1 character 
up with wrap. 


ATTDNM 
SPN 
Scroll the Sprite attributes l character 
down with wrap. 


GETBLS 
SPN, CDL, KM 
Block rrove screen data frOTI screen to 
Sprite. 


GETXRS 
SPN, CDL, KM 
Logically XOR screen data into Sprite data. 


GETORS 
SPN, OOL, KM 
Lo;Jically CR screen data into Sprite data. 


GETNDS 
SPN, (X)L, KM 
Logically AND screen data into Sprite data. 


PUTBLS 
SPN, CDL, KM 
Block rrove Sprite data fran Sprite to 
screen. 


PUTXRS 
SPN, CDL, KM 
Logically XOR Sprite data into screen data. 


PUTORS 
SPN, CDL, KM 
Logically CR Sprite data into screen data. 


PUTNDS 
SPN, CDL, KM 
Logically AND Sprite data into screen data. 


GWBLS 
SPN, (l)L, IOJ, 
Block rrove screen data Eron screen window 


OCOL, SROW, B:,T, 
into Sprite window. 


I.EN. 
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GWXRS 
SPN, (X)L, RCM, 
Lo3ically XOR screen data fran screen window 


OCOL, SR.OW, H:;T, 
into Sprite window. 
LEN 


GWORS 
SPN, (X)L, FO-J, 
Lo3ically OR screen data fran screen window 


SCOL, SROW, a::;rr, 
into Sprite window. 
LEN 


GWNDS 
SPN, (X)L, IO-J, 
Lo3ically AND screen data fran screen window 


OCOL, SRCM, IJ:iT, 
into Sprite window. 
LEN 


GWATTS 
SPN, (X)L, RCM, 
Block m:>ve attributes fran screen window into 
OCOL, SRCM, a:;T, 
Sprite window. 


LEN 


PW BLS 
SPN, OOL, KM, 
Block rrove Sprite data fran Sprite window 
S:::OL, SR.OW, Em, 
into screen window. 
LEN 


PWXRS 
SPN, OOL, Rai', 
Lo3ically XOR Sprite window data into screen 
OCOL, SROW, H:;T, 
window. 
LEN 


PWORS 
SPN, OOL, Rai', 
Logically CR Sprite windCM data into screen 


PWNDS 


PWATTS 


GWBLM 


GWXRM 


GWORM 


GWNDM 


GWATTM 


PWBLM 


PWXRM 


PWORM 
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OCOL, SROW, Em, 
windCM. 
LEN 


SPN, CDL, R:W, 
OCOL, SROW, B:;T, 
LEN 


SPN, OOL, KM, 
SXJL, SRCM', 83T, 
LEN 


SPl, SP2, OCOL, 
SRa-1 


SPl, SP2·, SXJL, 
SRa-1 


SPl, SP2, OCOL, 
5Ra'I 


SPl, SP2, OCOL, 
5Ra'I 


SPl, SP2, SXJL, 
SRa-1 


SPl, SP2, SXJL, 
SRa-1 


SPl, SP2, OCOL, 
SRa-1 


SPl, SP2, SXJL, 
SRCM 


Logically AND Sprite window data into screen 
window. 


Block rrove Sprite window attributes into 
screen windCM. 


Block m:>ve Sprite SPl into Sprite SP2 at 
SXJL,SROO. 


Logically XOR Sprite SPl into Sprite SP2 
ats:DL,SROi. 


Logically CR Sprite SPl into Sprite SP2 
at SX>L, SRO-l. 


Logically AND Sprite SPl into Sprite SP2 
at SX>L, SRCM. 


Bl ock rove attributes of Sprite SPl into 
Sprite SP2 at OCOL, SRO-J. 


Block nove window at OCOL, SRCM of Sprite 
SP2 into Sprite SPl. 


Logicall y XOR window at S:::OL, SRCM of Spr ite 
SP2 into Sprite SPl. 


Lcgically CR window at S::OL, SRCM of Sprite 
SP2 into Sprite SPL 


PWNDM 


P)NATTM 


COPYM 


COPXRM 


COPORM 


COPNDM 


COPATTM 


INW 


MIRV 


MARV 


INVM 


MIRM 


MARM 


SPINM 


DSPM 


HALT 


El 


DI 


EXX 


INT-ON 


INT-OFF 


PROG 


RESERVE 


GOTO 


RETUSR 


SPl, SP2, s:::oL, 
SRCW 


SPl, SP2,IS:OL, 
SRCW 


SPl, SP2 


SPl, SP2 


SPl, SP2 


SPl, SP2 


SPl, SP2 


im, IEN, OJL, 
IOI 


Im, IEN, OJL, 
IOI 


im, IEN, OJL, 
IOI 


SPN 


SPN 


SPN 


SPl, SP2 


SPl, SP2 


FORTH ,ORD 


Nl 


Nl 


Logically AND window "t SX>L,SIOI of Sprite 
SP2 into Sprite SPl. 


Block rrove attributes of window at 
S:OL,SROJ of Sprite SP2 into Sprite SPl. 


As G+JBIM blt SX>L,SRCM assurred zero. 


As G-JXPM. blt S:OL,SRDi assurred zero. 


As G'l)RM blt S:OL, SRCM' assurred zero. 


As G4NrM b.lt S:OL,SRCW assurred zero. 


As GWATIM b.it S:OL,.sR!:M assuned zero. 


Invert screen window. 


Mirror screen windc:M arout its centre. 


Mirror screen window attributes al:x:lut 
centre. 


Invert Sprite data. 


Mirror Sprite a.i:x:>Ut its centre. 


Mirror Sprite attributes alx>ut centre. 


Rotate Sprite SP2 90 deg-rees clockwise 
into Sprite SPl. 


Enlarge Sprite SP2 into Sprite SPl. 


Suspend CPU q;:>eration until next interrupt. 


Enable interrupt. 


Disable interrupt. 


Exchange Ideal variables with the alternate 
Ideal variables. 


Execute specified Forth Word under interrupt. 


Terminate execution of interrupt driven 
w:>rd. 


Enter eASIC. 


Reserve Nl bytes in the dictionary for 
eASIC source. 


Beqin execution of eASIC at line NL 


Return to eASIC fran RAND.:l-1.IZE t.SR 30000 
call. 
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DSPRITE 
SPN 
Delete Sprite and recover bytes fran below. 


!SPRITE 
SPN, im, LEN 
Create Sprite and rrove cur:rent Sprites 
down tD accam,::,date. 


WIPE 
SPN 
Delete Spd te and recover bytes fran above. 


SPRITE 
SPN, im, LEN 
Create Sprite at free space after last 
Sprite. 


RELOCATE 
MLEN 
Relocate Sprite space by signed. 16 bit 
length MLEN. 


COLD # 
SPST, SLEN 
Reset Sprite space to begin at SPST with 
SLEN bytes cleared to zeros. 


SETAV 
im, LEN, CDL, 
Fill the screen window with the current 


RCM 
attributes. 


SETAM 
SPN 
Fill the Sprite with the current attributes. 


CLSV 
!Gr, LEN, COL, 
Clear the screen window and fill with the 


RCM 
current attributes. 


CLSM 
SPN 
Clear the Sprite. 


ADJV 
im, LEN, aJL, 
Adjust the screen window to l ie on the 


RCM 
screen. 


ADJM 
SPN, CDL, RCM 
Adjust (X)L, R()il, mr, IEN, 9X)L, 5RO'l such 
that GE:TS and Pl1fS lie on the screen. 


AND 
Nl 
Leave a randan m.tnber bet~n O arrl Nl 
on the stack. 


OUT !, 
Nl, N2 
output ISB of Nl tD 16 bit port address N2. 


IN* 
Nl 
Leave oo the stack, byte £ran 16 bit port 
address Nl.. 


ZAPINT 
Create run tine program with interrupt 
facility. 


ZAP 
create run t.i.rre program without interrupt 
facility. 


CALL 
Nl 
Execute machine cx:rle subroutine at a:ldress 
NL 


KB 
Nl, N2 
Test for key press at rCM Nl, col N2 and 
stack true or false flag. 


SCANV 
(X)L , RCM 
The dlaracter positi on is scanned for screen 
data and a true or false flag stacked. 


SCANM 
SPN 
'Ibe Spri te i s scanne:l for data and a true 
or false fl ag stacked. 


BLEEP 
Nl, N2 
Sinclai r IEEP. 
Nl is durati on, N2 is pitch. 
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ATTON 


ATTOFF 


WORD 


COPY 


AT 


BORDER 


CLS 


DRAW-ARC 


CIRCLE 


DRAW 


PLOT 


SCREEN$ 


ATTA 


POINT 


TAB 


OVER 


INVERSE 


BRIGHT 


FLASH 


PAPER 


INK 


PARAMETERS 


Nl, N2 


Nl 


Nl, N2, N3 


Nl , N2, N3 


Nl, N2 


Nl , N2 


Nl, N2 


Nl, N2 


Nl, N2 


Nl 


Nl 


Nl 


Nl 


Nl 


Nl 


Nl 


Enable attritote switch. 


Disable attribute switch. 


FORT H/ BASIC GLOSSARY 


ACTION 


Cq>y screen to ZX-Printer. 


Move print position to Nl,N2. 


Set b:>rder CX>lour to N1. 


Clear whole screen, hone cursor and fill 
with current at tributes. 


±: X,±.Y,AN::iLE. 
As Sinclair' s cw,. 


X,Y,RADilE. 
"As Sinclair ' s own. 


±x,±Y. 
As Sinclair' s CW1. 


X,Y. 
As Sinclair' s own. 


Leave oo the stack the ASCII ccrle of the 
character at R'.'.M' Nl., OOL N2. 


Leave oo the stack the attribute ccrle of 
the character at KM Nl, (l)L N2. 


Test pixel at Nl ,N2 and leave a true or 
false flag on the stack. 


Set print position to CDL NL 


Zero or one, as Sinclair's o,,m, 


Zero or one, as Sinclair's Qo.'11. 


Zero or one, as Sinclair I s c,,,.n, 


Zero or ooe, as Sinclair's own. 


Set paper rolour , as Sinclair' s o,.,ri. 


Set ink colour, as Sinclair ' s o,,,,,n. 
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PRINT USR 24832 


PRINT USR 24836 


PRINT USR 30006 


RANDOMIZE USR 30000 


USR CALLS 


Enter Forth fran BASIC via a OJLD srART 


Enter Forth fran BASIC via a WARM srART 


Re-Enter Forth fran PA.SIC and oontinue 
execution of the next Forth w:::ird. 


Call Forth and continue execution 
up to the first occurence of the Forth 
,,,,;:)rd RETiJSR. 


EXTENDED SPECTRAFORTH GLOSSARY 


WORD 


PRT-ON 


PRT-OFF 


EDIT 


PARAMETERS 
ACTION 


Nl 


WARM->COLD 


K 


DUMP 


WARM 


EMITC 
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Nl 


Nl 


send all subsequent output to the printer. 


Send all subsequent output to the screen. 


Edit line number Nl fran the current screen. 


Create extenderl FORTH. 


Cq,y second loop index to the top of the 
stack. 


Cq,y third loop index to the top of the 
stack. 


Merory dunp fran address Nl . 


Perform a wum start. 


As EMIT tut cxmtrol characters are also 
su~rte:i. 


THE DEMONSTRATION PROGRAM - A BRIEF DESCRIPTION 


THE WHITE LIGHTNING SCREEN 


The green text at the top of the screen, sprites 59 and 60, is scrolled right in 
background. 


'];he lightning b:>lt, sprite 32, is p.1t to the screen using Plil'BLS. 
It is then 
mirrored and then mirrored again using MIRV. It is raooved fran the screen using 
PUTXRS. 


Tw'.> windallls are defined. over the '\'IUTE LIGlfl'NIN:i 1 , sprites 30 and• 31. 
The left 


window is scrolled left and the right window scrolled right using s::LSV and OCRSV 
respectively. 


THE TRAIN 


The steam engine is a:xnprised of sprites 9, with sprites 18, 19, 20, and 21 for 
the ...tleels in their four p::,sitions. 
The coaches are cx:mprised. of sprites 14 with 


sprites 23 and 24 for the wheels. 


The track, sprite 10, is scrolled left using ~IV. 
By neans of an increasing and 


decreasing delay loop, acceleration and decceleration effects are achieve:i. 


THE SPIDERS 


Five spiders, sprite 7, are placErl on the screen. 
Fran the left, spider 1 is 


scrolled dcMl'l. by 1 pixel, spider 3 is scrolled up 8 pixels and spider 5 is 
scrolled up 4 pixels all - in background. 


Spiders 2 and 4 are animated up and &,wn using sprites 7 and 8. 


THE SIDEWAYS SCROLLING CIRCLE OF INVADERS 


'l\oielve Invaders, sprite 24 , are placed in a circl e oo the screen, using e i ther 
~l.M., l'lffl.4M or \'RR8M they are scrolled in rreoory and then placed on the screen 
using PUTBIB. 


The Invader in the centre 0£1 the screen is scrolled left ~ 1 pixel in 
background. 


THE ARRAY OF CLOCKWORK TOYS 


The ~reen clockwork toys are animate::1 using sprites 49 and 50. 
F.ach sprite in the 


array is individualy placed on the screen using PlJI'BIS. 
The noverent is 


controlled by sirrple 'ro IOOPS'. 


THE VERTICAL ATTRIBUTE SCROLL 


Using ATI'UPV and decreasing and increasing delay lcq,s the attributes placed on 
the screen are 
scrolled up, whilst a randan b::>rder oolour change is executed. 
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THE THREE VEHICLE SCROLLING DEMO 


This darr:>nstrates the 3 precisions of scrolls available - 1, 4 and 8 pixels. 


Sprite 1, the vintage car, daronstrates the fine 1 pixel scroll using s:LlV. 


Sprite 2, the van, danonstrates the faster 4 pixel scroll using s:L4V. 


Sprite 3, the dragster, dem:mstrates, the ve.ry fast 8 pixel, or 1 character 
scroll, using S:LBV. 


THE TELEVISION 


The television, sprite 13, is placerl on the screen, a window" is defined inside the 
screen. 


Sprite 5, the dancer is used to dem::mstrate the 1 pixel scroll with wrap, WRRlV. 


Sprite 4, the duck, is use:i to dE!oonstrate the 4 pixel scrool with wrap, Mm4V. 


Sprite 6, the rocket, is used to dem:mstrate the 8 pixel scroll with wrap, WRRBV. 


THE THREE SPACESHIPS 


In this deoonstration the 3 spaceships, sprite 15, are placerl oo the screen along 
with their shadows, sprite 16. 


They are scrollecl to the right l::,_f 1 pixel, with alternate 1 pixel up and dawn 
scrolls, to give a sense of rrotion. 


The attributes of the forground, sprite 17, and the 1:ackground, sprite 11, are 
scrolled to the left. 
The backgroun:i being scrolled at one character per 


executi9n with the foregound l::eing scrolled two characters f)er execution to give a 
sense of f)erspective. 


THE BOUNCING MAN WITH HAT 


The b:>uncing nan is animated using sprites 28 and 29. 
The sprites are placed oo 


the screen using PU'IXRS, and removed again using Pl.IDCRS, such that the character 
appears t.o rrove l::ehind the '\>IUTE LIGffiNill;' text without destroying it. 


Sinple 00 !OOPS oontrol his path. 


Disabling interrupts, using DI, during the animation· appeared to reduce the slight 
flicker of the character, the interrupts \fbere enabled again using EI. 


THE CIRCLE OF ROTATING INVADERS 


Fron the original invader, sprite 24, sprites 25, 26 and 27 were created using the 
'KtrATE' facility of the sprite developnent package. 


This deno shows 0CM the centre invader, scrolling left by 1 pixel in backgrourrl, 
rroves at a constant SlOOth rate, indeperxlent fran that of the increasing and then 
decreasing rate of the rotating invaders in the outer circle. 
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THE PLAGUE OF CRABS 


The crabs, sprite 33, are placai oo the screen using PUI'BLS. 


The Em and O'.lL varables for the PUI'B[S are loade:l up each tine 17{ a randan nl.11lber 
produced by using the Forth "1Crd RND. 


THE BOUNCING BALL 


This is a sprite or to te ITOre precise, 4 sprites, rroving in background. 
The ball 


is defined in four orientations to give half character resolution. 
'Ibe rrovement 


i s obtained by doing a PU'IXRS, calculating the next arordinates, blotting oo.t the 
old sprite with a second PU'lXRS and then repeating the cycle. The listing for this 
screen is given in section 3 under the heading - Prograrmable Sprites. 


THE LUNAR SPACE SHIP 


The radar dish en top of the space ship, sprite 34, is animated by sequentially 
placing sprites 35 to 42, giving the effect of oonstant rotation. 


Just before the spaceship takes off , an explosion, sprite 43 , is XORed o.,er the 
spaceship using PUI'XRS. 
It is rarovai again by a second PlJIXRS. 


The spaceship is then scrolled ll' in a vert ical window by 1 pixel. 
'!be Lunar 


surface, sprite 44, is also scol l e:i by 1 pixel, to the right using mR.l V. 


THE ROTATING BALLS 


Four sprites \<e.l"e use:l to give the irrpression of rotation, these being sprites 45, 
46 , 47, and 48. 


Once the sprites were created, animation was a sirrple process of sequentially 
placing the sprites to the screen with an increasing and decreasing tirre delay 
between each Pl1I'BLS. 


THECREOITS 


To achieve the text scrolling 1.t) fran the 1:x>ttan of the screen, the tottan line 
was set with O INK and O PAPER colours, while the rest of the screen had 7 INK and 
0 PAPER colours. 


Each line of text ....as printed into that line and then the whole screen scrolle::l up 
8 * 1 pixel, such that the text data scrolls into the screen that has 7 INK 
attributes and thus appears to sn:iothly scroll onto the screen. 
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SOME SIMPLE PROGRAMMING EXAMPLES 


Example 1 


To scroll a windc:,.., at ITM 8, colurm 9, 
5 characters high by 10 characters long, 


pixel to the left with wrap - type: 


: DEMl 5 fl;T ! 10 LEN ! 8 ~ 
! 9 OJL ! ~lV ; <CR> 


To p.1t sane data on the screen type: VLIST <CR> 


To scroll the window 100 times type: 


: DEM2 100 0 IX) CEMl IOOP ; <O<> 
CEM2 <O<> 


To execute CEMl in background type: ' CEMl INT--ON <CR> 


To halt the background execution of WU type: :mT-OFF <ffi> 


Example2 


To scroll a window at ooll.ITIO 12, rcM 3, 10 characters high, and 5 characters wide, 
downward tr,, 3 pixels with wrap - type: 


: DEM3 10 H:;T ! 5 LEN ! -3 NPX ! 2 RCM ! 12 (X)L ! w::RV ; <CR> 


to define the l/oOrd, then CEM3 <CR> to execute it. 


To run CEM.3 in l:ackgrourrl type: 


' I:&13 INT~ <OD 


To halt the l:ackground execution type: INI'--OFF <CR> 


Example3 


To invert a windc,w at oolurm 10, row 5, 4 characters high and 4 characters wide - 
type: 


: CEM4 4 fliT l 4 IBN ! 5 ROO ! 10 ClJL l INW ; <O<> 


and then I:EM4 <CR> to execute. 


Example4 


It i s oot always necassary to use oolon definitions to achieve a particular 
result. 
To Pl1l' sprite 34 (If you•~ got the Derro sprites loade1 or have already 


defined your a.m sprite 34) at ITM 5, colunn 6, and replace any data currently at 
that position - type: 


34 SPN ! 5 IOI ! 6 ClJL I PIJl'BIS <O<> 
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Example& 


Often it is useful to define a ~rd which carries out an cperation that is use:i 
frequently and which saves typing - for instance: 


: OEMS OOL ! ROol' ! SPN ! Pll!'BIS ; 


If we wanted to carry out the sill'ple PUl' ccmnand in exarrple 4 all we'd nee:l to 
type would be: 


34561»!5 


Example& 


To scroll sprite 29 in rrerory by l pixel to the right with wrap and rur it on the 
screen at rrM 10, oolunn. 11 - use: 


: 1»16 29 SPN I 10 RCW ! 11 OOL ! WRRlM Pl1l'Bl.S 


To run r:f.M6 in backgrourrl use: ' Il!M6 INT--CN 


ltxample7 


To fill a screen win&::,,,,,, at colum 17, ITM 5, 5 characters long and 10 characters 
high, with the attributes - 
6 INK, 2 PAPER and 1 FIA5H - use the follCMing: 


: 1»17 l F[ASll 6 INK 2 PAPm 10 IG1' ! 5 LEN ! 13 !CW I 17 OOL ! SF:rAV 0 FLASH 7 
INK 1 PAPm 


Example& 


To dlange the green face of sprite 28 into a re:i ooe use: 


: 1»18 28 SPN ! 2 INK ! l ERIGHT 0 PAPm SF:r/\M P!Tl'BLS ; 


Example9 


To pick a randan number 1:etween O and 100 use: 


: 1»19 100 RND • 


Example 10 


To pi ck a randan INK oblour and change sprite 34' s INK colour to this colour, and 
then p.it it at column 10, rCM 10 use: 


: 1»110 7 RND INK 34 SPN ! SEr/\M 10 !CW ! 10 OOL ! PUTBIS ; 


To run DF.Ml0 in background use: ' 00-110 INI'--ON and to halt l»fl0 use INT-OFF. 
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Example 11 


To place sprite 24 into the screen of sprite 13 use: 


I»ll.l 24 SP1 ! 13 SP2 ! 7 S'.XlL ! 6 SROW ! G<BIM 10 RO< 
10 (l)L 
ATION PUTBLS 


Example12 


To XOR sprite 43, th~ explosion, with sprite 27, the 270 Cl83'ree rotated Invader, 
in rre:rory use: 


: DEM12 43 SPl ! 27 SP2 ! OOPXR."1. 10 RCW ! 10 OOL ! 27 SPN ! ATION P01'BLS ; 


Example 13 


To invert sprite 7, the spider, in IfBOOry use: 


: IE413 7 SPN ! INVM 10 RO< ! 10 CXlL ! PUTBLS ; 


Example14 


To-enlarge sprite 24 into sprite 45 using the DSPM a:mnand use: 


: !E414 45 SPl ! 24 SP2 ! OOPM 45 SPN ! 10 (l)L ! 10 RO< ! PUTBLS 


Example16 


To search throi.:gh sprite space, locate any existing sprites, print out the start 
of data, length and height use: 


: IE415 255 l 00 I SPN ! TEST l = IF I. SPl\CE IP1R @ U. SPl\CE IBN ? SPl\CE !GT ? 
SPl'CE Cll lliEN IOOP 


Example18 


To scroll a landscape sprite numbered 128, 2 characters high and 64 characters 
wide, left by 1 pixel under interrupt, use the following: 


s:R • 6 
0 0 Vl\RIAllLE 0:. 8 VARIABLE PH : OPEN EKX O (l)L l 12 RO< ! 2 !GT I 
l O ffiOi I O S'.XlL I 128 SPN I O PAPER 6 INK 32 IBN ! O:.SV O INK 
2 l IEN ! O:.SV 32 IBN ! IWB!.S EKX ; 
3 
NXB 0:. @ l+ CUP 64 = IF mJP O ENDIF CUP 0:. I 31 + 64 !OD S'.XlL 
4!1IEN!:EWil'.S32IEN!; 
5 : SL liU.lV PH @ 1- CUP 0= IF NXB mJP 8 ENDIF PH ! ; 
6 : CD 6 INK O PAPER O lDRilER l IRIGHT O:.S 14 Im ! l CXlL 
7 6 PAPER 31 IEN ! 4 !GT I SF:rAV OPEN 6 INK ' SL INl'-00 ; 


To speed this q,, to faster 4 or 8 pixel scrolls change lines 0 and 5 to read: 


0 0 VARIABLE 0:. 2 Vl\RIAllLE PH : OPEN EKX O (l)L I 12 RJW I 2 !GT I 
5 
SL liU.4V PH @ 1- CUP 0= IF NXB mJP 2 ENDIF PH I ; 


0 : Vl\RIAllLE 0:. l VARIABLE PH : OPEN EKX O (l)L ! 12 Im 
2 !GT 
5 : SL iiU.SV PH @ 1- CUP O= IF NXB mJP l ENDIF PH ! ; 


Type: 6 IOAD <CR> to OCIT{)ile and CD <CR> to run. 


131 


ERRATA - \tlUTE LIGH'!Nlll; MANUAL 


Page 7, line 24: 
"enter the number 75" should read 
"enter the number 63 ". 


Page 20, line 19: 
" 
Convert the number .•• trailing 


space" should read 
II 
Convert the number 
II etc. 


Page 72, line 25: 
":EWI'XRM" should read "PWXRM". 


Page 75, OCR#G, lines 6 & 7: 
Remove BP.SE fran line 6 and place 
at end of line 7. 
( ••• IOOP O OAT BP.SE;) 


Page 104, DUMP: 
"addr n ---" should read "addr ---" 


Throughout the rranual, the Forth \\Ord 
"-->" is constructed as "- - >", i.e. 
two minus signs and a greater than. 


